From 4b3cdede1be8f9f57dbc6faca328e8f9022582e3 Mon Sep 17 00:00:00 2001 From: Paul Bakaus Date: Wed, 8 Apr 2026 10:07:30 -0700 Subject: [PATCH] Editorial wrappers for 7 refine-category skills Second batch. Covers the seven skills that improve existing interfaces along a single dimension at a time. - typeset: fix generic typography (fonts, hierarchy, scale, readability) - arrange: fix layout, spacing, and visual rhythm - colorize: add strategic color to monochrome interfaces without slop - animate: purposeful motion that conveys state, never decoration - delight: small personality moments that turn functional into memorable - bolder: push safe designs toward impact without sliding into loud - quieter: tone down overstimulating designs while keeping their intent Each wrapper keeps the four-section template (When to use it / How it works / Try it / Pitfalls), stays concrete, flags the neighboring skill when the user is reaching for the wrong tool, and calls out the explicit anti-patterns each skill refuses to produce (bounces for animate, extra colors for colorize, decoration for the rest). --- content/site/skills/animate.md | 43 +++++++++++++++++++++++++++++++++ content/site/skills/arrange.md | 41 +++++++++++++++++++++++++++++++ content/site/skills/bolder.md | 40 ++++++++++++++++++++++++++++++ content/site/skills/colorize.md | 38 +++++++++++++++++++++++++++++ content/site/skills/delight.md | 42 ++++++++++++++++++++++++++++++++ content/site/skills/quieter.md | 40 ++++++++++++++++++++++++++++++ content/site/skills/typeset.md | 42 ++++++++++++++++++++++++++++++++ 7 files changed, 286 insertions(+) create mode 100644 content/site/skills/animate.md create mode 100644 content/site/skills/arrange.md create mode 100644 content/site/skills/bolder.md create mode 100644 content/site/skills/colorize.md create mode 100644 content/site/skills/delight.md create mode 100644 content/site/skills/quieter.md create mode 100644 content/site/skills/typeset.md diff --git a/content/site/skills/animate.md b/content/site/skills/animate.md new file mode 100644 index 000000000..a758bc6ce --- /dev/null +++ b/content/site/skills/animate.md @@ -0,0 +1,43 @@ +--- +tagline: "Purposeful motion that conveys state, not decoration." +--- + +## When to use it + +`/animate` is for interfaces that feel lifeless, where state changes are instant and jarring, where loading just pops in, where the user never quite trusts that their click registered. Use it to add the small motions that communicate what is happening: entrances, exits, feedback, transitions between states. + +Do not use it to add bounces or elastic springs for the sake of energy. That is decoration, and this skill will not give it to you. + +## How it works + +The skill identifies static moments that would benefit from motion, then applies them with strict discipline: + +1. **Entrances and exits**: elements appear and leave with 200 to 300ms fades plus subtle Y or scale, never layout properties. +2. **State feedback**: hover, active, focus, loading, success all communicate via motion instead of sudden swaps. +3. **Transitions between views**: shared-element transitions where it makes sense, fade-through otherwise. +4. **Progress and loading**: skeleton screens, determinate bars, motion that says "still working". +5. **Reduced motion**: every animation has a `prefers-reduced-motion` fallback. + +Easing is always exponential (ease-out-quart, quint, or expo) because real objects decelerate smoothly. No bounce, no elastic, no linear for anything except progress indicators. + +The skill animates `transform` and `opacity` only. If you find yourself animating `width`, `height`, `top`, or `left`, it is doing the wrong thing. Use `grid-template-rows` for height transitions. + +## Try it + +``` +/animate the sign-up flow +``` + +Typical additions: + +- Email input gets a focus glow on focus-visible (opacity + shadow, 180ms) +- Submit button shows a spinner inside itself on loading state, not a separate spinner next to it +- Success screen enters with opacity + translateY(8px), 260ms, ease-out-quart +- Error message slides down with grid-template-rows (not height), 220ms +- `@media (prefers-reduced-motion: reduce)` fallback for every transition + +## Pitfalls + +- **Asking for "more animation".** Animate is not a dial. It adds where motion communicates, not everywhere. +- **Animating layout properties.** Never `width`, `height`, `top`, `left`, `padding`, `margin`. Transform and opacity only. +- **Skipping reduced-motion fallbacks.** Non-negotiable for accessibility. Animate will add them; do not remove them. diff --git a/content/site/skills/arrange.md b/content/site/skills/arrange.md new file mode 100644 index 000000000..5144ee508 --- /dev/null +++ b/content/site/skills/arrange.md @@ -0,0 +1,41 @@ +--- +tagline: "Fix layout, spacing, and visual rhythm." +--- + +## When to use it + +`/arrange` is for pages where nothing is technically wrong but nothing is breathing either. Equal padding everywhere, monotonous card grids, content that runs edge to edge, hierarchy that relies on size alone. Reach for it when a layout "feels off" and you cannot articulate why. + +Good triggers: "everything feels crowded", "it reads like a wall", "I do not know where to look first". + +## How it works + +The skill runs through five layout dimensions: + +1. **Spacing**: is the spacing scale consistent or are there random 13px gaps, are related elements grouped tightly with generous space between groups, is there any rhythm at all. +2. **Visual hierarchy**: does the eye land on the primary action within 2 seconds, is the hierarchy doing real work or is everything shouting. +3. **Grid and structure**: is there an underlying grid or is the layout random, are elements aligned to baselines. +4. **Rhythm**: does the page alternate between tight and generous spacing, or is everything uniform. +5. **Density**: is the layout cramped or is it wasteful, does density match the content type. + +Fixes usually involve rebuilding the spacing scale, introducing asymmetry, collapsing monotonous grids into a mixed layout with hero and supporting elements, and giving the primary action real space. + +## Try it + +``` +/arrange the settings page +``` + +Typical changes: + +- Spacing scale unified to 8 / 16 / 24 / 48 / 96px +- Section breaks at 48px, row gaps at 16px, form field groups at 8px +- Primary actions pulled out of the form flow with 32px buffer +- Decorative borders removed, replaced with spacing-driven grouping +- Sidebar and main column proportions rebalanced (280 / flex vs 25 / 75) + +## Pitfalls + +- **Confusing arrange with distill.** If the problem is too many things, run `/distill` first. Arrange is for arranging what is already the right set. +- **Expecting it to rescue a broken grid.** If the page has no grid at all, arrange will build one. Just know that the diff is going to be larger than you expect. +- **Ignoring the hierarchy verdict.** If arrange says "nothing is primary", no amount of spacing work fixes that. You need a content decision, not a layout tweak. diff --git a/content/site/skills/bolder.md b/content/site/skills/bolder.md new file mode 100644 index 000000000..2445c097d --- /dev/null +++ b/content/site/skills/bolder.md @@ -0,0 +1,40 @@ +--- +tagline: "Push safe designs toward impact without sliding into chaos." +--- + +## When to use it + +Reach for `/bolder` when the interface looks like every other interface. Generic sans, medium weights, soft shadows, modest accent color, reasonable spacing, forgettable. The design is not wrong, it is just safe. Use bolder when a project can handle presence and the current state is not bringing any. + +Do not use it on dashboards people stare at for hours. Boldness earns its place on marketing pages, hero moments, and content features. Not in operator tools. + +## How it works + +The skill amplifies four axes without breaking usability: + +1. **Scale**: display type gets pushed to clamp(3rem, 6vw, 6rem) or beyond. Headlines that fill the viewport, not hedge it. +2. **Weight contrast**: light 300 against heavy 800 instead of medium against regular. Real tension, not a shrug. +3. **Color commitment**: the accent color shows up at full strength, not diluted. Backgrounds can take a stance (ink, accent, cream) instead of all-paper. +4. **Compositional confidence**: asymmetry, off-grid, pullquotes, hanging punctuation, scale jumps. The layout has a voice. + +The skill does not add more. It amplifies what is already there. If the design has three colors, bolder does not add a fourth, it commits harder to the three. + +## Try it + +``` +/bolder the landing page hero +``` + +Expected changes: + +- Hero heading from 3rem to clamp(3.5rem, 7vw, 6.5rem), display font, weight 700 +- Subhead from regular to italic at 1.5rem, pulled 8px left of the heading for optical alignment +- Background switches from paper to a cream-to-paper gradient, creating a warmer container +- CTA button fills, drops shadow removed, border radius reduced, hover state inverts colors +- Supporting image pushed slightly off-grid with a negative top margin, creating asymmetry + +## Pitfalls + +- **Running it on the wrong page.** Product dashboards, settings, and forms should not be bold. They should be legible. Use `/arrange` or `/polish` instead. +- **Confusing bold with loud.** Bold means committed and confident. Loud means shouting. Bolder is the former. If the result feels aggressive, follow up with `/quieter`. +- **Pairing it with `/delight` in the same pass.** Delight works best against a stable visual baseline. Bold first, stabilize, then delight. diff --git a/content/site/skills/colorize.md b/content/site/skills/colorize.md new file mode 100644 index 000000000..9617abbd4 --- /dev/null +++ b/content/site/skills/colorize.md @@ -0,0 +1,38 @@ +--- +tagline: "Add strategic color to monochrome interfaces without going garish." +--- + +## When to use it + +`/colorize` is the counterweight to "everything is gray". Dashboards that read as a beige wall, forms with no accent, content pages that could be any SaaS product. Reach for it when the interface is functional but emotionally flat, and you want warmth without tipping into the AI color palette (purple-to-pink, cyan neon, dark mode glow). + +## How it works + +The skill starts by reading your brand color if one exists, then decides where color earns its place: + +1. **Primary action** gets the strongest expression of the brand hue. +2. **Secondary accents** get muted or tinted variants, not a second full color. +3. **Neutrals** get tinted toward the brand hue at low chroma (around 0.005 to 0.01), which is nearly invisible per pixel but creates subconscious cohesion. +4. **Content categories** get a limited, intentional accent system, not a rainbow. + +Importantly, it uses OKLCH rather than HSL so that equal lightness steps look equal. As lightness moves toward the extremes, chroma drops automatically. This is how you get color that feels considered instead of computed. + +## Try it + +``` +/colorize the dashboard +``` + +Expected diff: + +- Brand color moved from a hardcoded hex to `--color-accent: oklch(62% 0.18 240)` +- Neutrals tinted with 0.007 chroma toward the brand hue +- Primary button gets the full accent, secondary buttons get ink/mist +- Chart series uses 3 distinct hues, all at matched lightness so no series visually dominates +- Empty state illustration picks up a soft accent wash + +## Pitfalls + +- **Running it without a brand hue.** Colorize needs a starting point. If `.impeccable.md` does not specify one, it will ask. Do not let it pick from the AI color palette defaults. +- **Expecting it to fix the AI color palette problem.** If your design already has purple gradients and cyan neon, you need `/quieter` first, then colorize can rebuild. +- **Using it on already-colorful interfaces.** That is a `/quieter` job. Colorize adds, it does not subtract. diff --git a/content/site/skills/delight.md b/content/site/skills/delight.md new file mode 100644 index 000000000..fbd9e805a --- /dev/null +++ b/content/site/skills/delight.md @@ -0,0 +1,42 @@ +--- +tagline: "Small moments of personality that turn functional into memorable." +--- + +## When to use it + +`/delight` is for interfaces that work but do not feel like anything. Use it when the core experience is solid and you want to add the small human touches that make people remember it: a considered empty state, a loading message with a point of view, a success animation that feels earned, a microcopy moment that makes someone smile. + +It is a finishing skill. Never the first thing you run on a new build. + +## How it works + +The skill hunts for delight opportunities in the places most designers skip: + +1. **Empty states**: instead of "No items yet", something with personality appropriate to the brand. +2. **Loading and waiting moments**: the best products turn waits into content. +3. **Success feedback**: a moment of celebration when something worth celebrating happens. +4. **Microcopy**: button labels, tooltips, error messages, placeholder text. Tiny copy with taste. +5. **Easter eggs and secondary states**: things users discover that reward paying attention. + +The skill reads the brand tone from `.impeccable.md`. A serious analytics tool gets serious delight (dry, precise, a little clever). A playful consumer app gets more overt personality. It does not force humor where humor is wrong for the audience. + +The rule is: every delight moment must still work perfectly if you delete the delight. Nothing depends on the smile. + +## Try it + +``` +/delight the first-run experience +``` + +Expected additions: + +- Empty dashboard replaces "No data yet" with "Your dashboard is quiet. Let's fix that." plus a single-action CTA. +- Initial sync gets a 3-state loading message that advances: "Finding your accounts... / Pulling the last 30 days... / Making it look good...". +- First successful action triggers a one-time toast with a tiny celebratory moment. After that, just a quiet checkmark. +- Help tooltip on the tricky field has a voice that sounds like a person wrote it. + +## Pitfalls + +- **Forcing humor.** Not every brand is playful. If the brand voice in `.impeccable.md` is "clinical and precise", delight adds clever restraint, not jokes. +- **Over-decorating.** One moment of delight is memorable. Twenty becomes noise. The skill is conservative on purpose. +- **Running delight before polish.** Polish fixes what is wrong. Delight adds what is missing. In that order. diff --git a/content/site/skills/quieter.md b/content/site/skills/quieter.md new file mode 100644 index 000000000..fedaa4d7c --- /dev/null +++ b/content/site/skills/quieter.md @@ -0,0 +1,40 @@ +--- +tagline: "Tone down designs that are shouting without losing their intent." +--- + +## When to use it + +`/quieter` is the counterweight to `/bolder`. Reach for it when an interface is visually aggressive, overstimulating, or trying to do too many things at full volume. Neon on dark, gradient text everywhere, 6 accent colors, everything animated, 20px shadows. Use quieter when the design needs to breathe and you want refinement without losing the point of view. + +Also useful after `/bolder` goes a little too far. + +## How it works + +The skill works by reduction across four axes: + +1. **Color**: desaturate, lower chroma in OKLCH, pull accents back to a single primary plus muted support. No more than two intentional colors. +2. **Contrast**: soften extreme darks and lights, pull the range in. Backgrounds move from pure white and pure black to paper and ink. +3. **Decoration**: remove shadows that are not doing work, drop borders that are not carrying structure, retire gradients that exist for energy rather than hierarchy. +4. **Motion and effect**: slow animations down, remove anything that auto-plays, drop parallax and blur unless they serve readability. + +The skill preserves the design's intent. If the original had a point of view, the quieter version has the same point of view with more confidence. Refinement, not neutralization. + +## Try it + +``` +/quieter the pricing page +``` + +Typical diff: + +- Gradient text on the price removed, replaced with solid ink at one weight heavier +- Three accent colors reduced to one (magenta), the other two become neutral variants +- Card shadows reduced from `0 20px 40px rgba(0,0,0,0.2)` to `0 1px 0 var(--color-mist)` (a hairline) +- Background switches from dark gradient to paper with a subtle cream wash at the top +- Hero animation from 1.2s easeOut with 3 staggered elements to a single 260ms fade-in + +## Pitfalls + +- **Over-applying.** Quieter can strip personality if you run it on something that was already measured. Use it when the design is too loud, not when it is correctly assertive. +- **Confusing quieter with distill.** Quieter reduces intensity. Distill removes elements. They are different moves. +- **Running it in response to a critique that says "too busy".** Busy usually means too many things, not too loud. Try `/distill` first. diff --git a/content/site/skills/typeset.md b/content/site/skills/typeset.md new file mode 100644 index 000000000..079661297 --- /dev/null +++ b/content/site/skills/typeset.md @@ -0,0 +1,42 @@ +--- +tagline: "Fix typography that feels generic, inconsistent, or accidental." +--- + +## When to use it + +Reach for `/typeset` when the text on a page looks like default typography instead of designed typography. Muddy hierarchy, three sizes that look the same, body copy at 14px, a display font that is actually just Inter bold, headlines with no kerning attention. + +Common triggers: "hierarchy feels flat", "readability is off", "fonts look generic". + +## How it works + +The skill assesses typography across five dimensions: + +1. **Font choices**: are you using invisible defaults (Inter, Roboto, Arial, Open Sans), does the typeface match the brand, are there more than 2 to 3 families. +2. **Hierarchy**: are heading, body, and caption clearly different at a glance, is the size contrast at least 1.25x between steps, are weight contrasts legible. +3. **Sizing and scale**: is there a coherent type scale, does body text meet 16px minimum, is the scale fixed-rem for app UIs or fluid-clamp for marketing pages. +4. **Readability**: line length 45 to 75 characters, line-height tuned for font and context, contrast. +5. **Consistency**: same element uses same treatment everywhere, no one-off font-size overrides. + +It then fixes what it finds: picks distinctive typefaces, builds a modular scale, widens hierarchy contrast, sets proper line length and leading. + +## Try it + +``` +/typeset the article layout +``` + +Expected diff: + +- Display font swapped from Inter 700 to a real display face +- Type scale rebuilt: 3rem / 2rem / 1.25rem / 1rem / 0.875rem, ratio 1.333 +- Body text bumped from 14px to 16px +- Line length clamped to 68ch on the article column +- Line-height 1.6 for body, 1.1 for display +- Removed four one-off `font-size` values scattered in component styles + +## Pitfalls + +- **Asking for a new font without context.** Typeset will pick based on the `.impeccable.md` brand voice. If you have not run `/impeccable teach`, the suggestion will be generic. +- **Reaching for typeset when the issue is layout.** If paragraphs are fine but the page feels cramped, you want `/arrange`. +- **Expecting fluid clamp scales on app UIs.** Typeset uses fixed rem scales for app interfaces. Fluid typography is for marketing and content pages where line length varies dramatically.