diff --git a/.agents/skills/impeccable/SKILL.md b/.agents/skills/impeccable/SKILL.md index fd3411c3..25044b37 100644 --- a/.agents/skills/impeccable/SKILL.md +++ b/.agents/skills/impeccable/SKILL.md @@ -32,8 +32,8 @@ Other harnesses should follow the same checklist when they can expose this state Two files, case-insensitive. The loader looks at the project root by default and falls back to `.agents/context/` and `docs/` if the root is clean. Override with `IMPECCABLE_CONTEXT_DIR=path/to/dir` (absolute or relative to cwd). -- **PRODUCT.md** — required. Users, brand, tone, anti-references, strategic principles. -- **DESIGN.md** — optional, strongly recommended. Colors, typography, elevation, components. +- **PRODUCT.md**: required. Users, brand, tone, anti-references, strategic principles. +- **DESIGN.md**: optional, strongly recommended. Colors, typography, elevation, components. Load both in one call: @@ -45,7 +45,7 @@ Consume the full JSON output. Never pipe through `head`, `tail`, `grep`, or `jq` If the output is already in this session's conversation history, don't re-run. Exceptions requiring a fresh load: you just ran `$impeccable teach` or `$impeccable document` (they rewrite the files), or the user manually edited one. -`$impeccable live` already warms context via `live.mjs` — if you've run `live.mjs`, don't also run `load-context.mjs` this session. +`$impeccable live` already warms context via `live.mjs`. If you've run `live.mjs`, don't also run `load-context.mjs` this session. If PRODUCT.md is missing, empty, or placeholder (`[TODO]` markers, <200 chars): run `$impeccable teach`, then resume the user's original task with the fresh context. If the original task was `$impeccable craft`, resume into `$impeccable shape` before any implementation work. @@ -53,7 +53,7 @@ If DESIGN.md is missing: nudge once per session (*"Run `$impeccable document` fo ### 2. Register -Every design task is **brand** (marketing, landing, campaign, long-form content, portfolio — design IS the product) or **product** (app UI, admin, dashboard, tool — design SERVES the product). +Every design task is **brand** (marketing, landing, campaign, long-form content, portfolio: design IS the product) or **product** (app UI, admin, dashboard, tool: design SERVES the product). Identify before designing. Priority: (1) cue in the task itself ("landing page" vs "dashboard"); (2) the surface in focus (the page, file, or route being worked on); (3) `register` field in PRODUCT.md. First match wins. @@ -63,24 +63,24 @@ Load the matching reference: [reference/brand.md](reference/brand.md) or [refere ## Shared design laws -Apply to every design, both registers. Match implementation complexity to the aesthetic vision — maximalism needs elaborate code, minimalism needs precision. Interpret creatively. Vary across projects; never converge on the same choices. GPT is capable of extraordinary work — don't hold back. +Apply to every design, both registers. Match implementation complexity to the aesthetic vision: maximalism needs elaborate code, minimalism needs precision. Interpret creatively. Vary across projects; never converge on the same choices. GPT is capable of extraordinary work. Don't hold back. ### Color -- Use OKLCH. Reduce chroma as lightness approaches 0 or 100 — high chroma at extremes looks garish. +- Use OKLCH. Reduce chroma as lightness approaches 0 or 100; high chroma at extremes looks garish. - Never use `#000` or `#fff`. Tint every neutral toward the brand hue (chroma 0.005–0.01 is enough). - Pick a **color strategy** before picking colors. Four steps on the commitment axis: - - **Restrained** — tinted neutrals + one accent ≤10%. Product default; brand minimalism. - - **Committed** — one saturated color carries 30–60% of the surface. Brand default for identity-driven pages. - - **Full palette** — 3–4 named roles, each used deliberately. Brand campaigns; product data viz. - - **Drenched** — the surface IS the color. Brand heroes, campaign pages. + - **Restrained**: tinted neutrals + one accent ≤10%. Product default; brand minimalism. + - **Committed**: one saturated color carries 30–60% of the surface. Brand default for identity-driven pages. + - **Full palette**: 3–4 named roles, each used deliberately. Brand campaigns; product data viz. + - **Drenched**: the surface IS the color. Brand heroes, campaign pages. - The "one accent ≤10%" rule is Restrained only. Committed / Full palette / Drenched exceed it on purpose. Don't collapse every design to Restrained by reflex. ### Theme Dark vs. light is never a default. Not dark "because tools look cool dark." Not light "to be safe." -Before choosing, write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force the answer, it's not concrete enough — add detail until it does. +Before choosing, write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force the answer, it's not concrete enough. Add detail until it does. "Observability dashboard" does not force an answer. "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room" does. Run the sentence, not the category. @@ -120,10 +120,10 @@ Match-and-refuse. If you're about to write any of these, rewrite the element wit If someone could look at this interface and say "AI made that" without doubt, it's failed. Cross-register failures are the absolute bans above. Register-specific failures live in each reference. -**Category-reflex check.** Run at two altitudes — the second one catches what the first one misses. +**Category-reflex check.** Run at two altitudes; the second one catches what the first one misses. -- **First-order:** if someone could guess the theme + palette from the category alone — "observability → dark blue", "healthcare → white + teal", "finance → navy + gold", "crypto → neon on black" — it's the first training-data reflex. Rework the scene sentence and color strategy until the answer isn't obvious from the domain. -- **Second-order:** if someone could guess the aesthetic family from category-plus-anti-references — "AI workflow tool that's not SaaS-cream → editorial-typographic", "fintech that's not navy-and-gold → terminal-native dark mode" — it's the trap one tier deeper. The first reflex was avoided; the second wasn't. Rework until both answers are not obvious. The brand register's [reflex-reject aesthetic lanes](reference/brand.md) list catches the currently-saturated families. +- **First-order:** if someone could guess the theme + palette from the category alone ("observability → dark blue", "healthcare → white + teal", "finance → navy + gold", "crypto → neon on black"), it's the first training-data reflex. Rework the scene sentence and color strategy until the answer isn't obvious from the domain. +- **Second-order:** if someone could guess the aesthetic family from category-plus-anti-references ("AI workflow tool that's not SaaS-cream → editorial-typographic", "fintech that's not navy-and-gold → terminal-native dark mode"), it's the trap one tier deeper. The first reflex was avoided; the second wasn't. Rework until both answers are not obvious. The brand register's [reflex-reject aesthetic lanes](reference/brand.md) list catches the currently-saturated families. ## Commands @@ -153,13 +153,13 @@ If someone could look at this interface and say "AI made that" without doubt, it | `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) | | `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) | -Plus two management commands — `pin ` and `unpin `, detailed below. +Plus two management commands: `pin ` and `unpin `, detailed below. ### Routing rules -1. **No argument** — render the table above as the user-facing command menu, grouped by category. Ask what they'd like to do. -2. **First word matches a command** — load its reference file and follow its instructions. Everything after the command name is the target. -3. **First word doesn't match** — general design invocation. Apply the setup steps, shared design laws, and the loaded register reference, using the full argument as context. +1. **No argument**: render the table above as the user-facing command menu, grouped by category. Ask what they'd like to do. +2. **First word matches a command**: load its reference file and follow its instructions. Everything after the command name is the target. +3. **First word doesn't match**: general design invocation. Apply the setup steps, shared design laws, and the loaded register reference, using the full argument as context. Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke `$impeccable`. @@ -173,4 +173,4 @@ If the first word is `craft`, setup still runs first, but [reference/craft.md](r node .agents/skills/impeccable/scripts/pin.mjs ``` -Valid `` is any command from the table above. Report the script's result concisely — confirm the new shortcut on success, relay stderr verbatim on error. \ No newline at end of file +Valid `` is any command from the table above. Report the script's result concisely. Confirm the new shortcut on success, relay stderr verbatim on error. \ No newline at end of file diff --git a/.agents/skills/impeccable/reference/adapt.md b/.agents/skills/impeccable/reference/adapt.md index 249653d4..21bb0255 100644 --- a/.agents/skills/impeccable/reference/adapt.md +++ b/.agents/skills/impeccable/reference/adapt.md @@ -1,6 +1,6 @@ > **Additional context needed**: target platforms/devices and usage contexts. -Adapt existing designs to work effectively across different contexts - different screen sizes, devices, platforms, or use cases. +Adapt an existing design to a different context: another screen size, device, platform, or use case. The trap is treating adaptation as scaling. The job is rethinking the experience for the new context. --- @@ -27,7 +27,7 @@ Understand what needs adaptation and why: - What won't work? (Hover states on touch, tiny touch targets) - What's inappropriate? (Desktop patterns on mobile, mobile patterns on desktop) -**CRITICAL**: Adaptation is not just scaling - it's rethinking the experience for the new context. +**CRITICAL**: Adaptation is rethinking the experience for the new context, not scaling pixels. ## Plan Adaptation Strategy @@ -164,7 +164,7 @@ Choose appropriate breakpoints: - Persistent side navigation on desktop - Breadcrumbs on smaller screens for context -**IMPORTANT**: Test on real devices, not just browser DevTools. Device emulation is helpful but not perfect. +**IMPORTANT**: Test on real devices. Device emulation in DevTools is helpful but not perfect. **NEVER**: - Hide core functionality on mobile (if it matters, make it work) @@ -187,4 +187,4 @@ Test thoroughly across contexts: - **Edge cases**: Very small screens (320px), very large screens (4K) - **Slow connections**: Test on throttled network -Remember: You're a cross-platform design expert. Make experiences that feel native to each context while maintaining brand and functionality consistency. Adapt intentionally, test thoroughly. +When the adaptation feels native to each context, hand off to `$impeccable polish` for the final pass. diff --git a/.agents/skills/impeccable/reference/animate.md b/.agents/skills/impeccable/reference/animate.md index b38e140f..48b5e268 100644 --- a/.agents/skills/impeccable/reference/animate.md +++ b/.agents/skills/impeccable/reference/animate.md @@ -1,6 +1,6 @@ > **Additional context needed**: performance constraints. -Analyze a feature and strategically add animations and micro-interactions that enhance understanding, provide feedback, and create delight. +Add motion that conveys state, gives feedback, and clarifies hierarchy. Cut motion that exists only for decoration. Animation fatigue is a real cost; spend the budget on the moments that need it. --- @@ -8,7 +8,7 @@ Analyze a feature and strategically add animations and micro-interactions that e Brand: orchestrated page-load sequences, staggered reveals, scroll-driven animation. Motion is part of the voice; one well-rehearsed entrance beats scattered micro-interactions. -Product: 150–250 ms on most transitions. Motion conveys state — feedback, reveal, loading, transitions between views. No page-load choreography; users are in a task and won't wait for it. +Product: 150–250 ms on most transitions. Motion conveys state: feedback, reveal, loading, transitions between views. No page-load choreography; users are in a task and won't wait for it. --- @@ -105,12 +105,12 @@ Use appropriate techniques for each animation: **Easing curves (use these, not CSS defaults):** ```css -/* Recommended - natural deceleration */ ---ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1); /* Smooth, refined */ +/* Recommended: natural deceleration */ +--ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1); /* Smooth */ --ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1); /* Slightly snappier */ --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1); /* Confident, decisive */ -/* AVOID - feel dated and tacky */ +/* AVOID: feel dated and tacky */ /* bounce: cubic-bezier(0.34, 1.56, 0.64, 1); */ /* elastic: cubic-bezier(0.68, -0.6, 0.32, 1.6); */ ``` @@ -153,12 +153,12 @@ Use appropriate techniques for each animation: ``` **NEVER**: -- Use bounce or elastic easing curves—they feel dated and draw attention to the animation itself +- Use bounce or elastic easing curves; they feel dated and draw attention to the animation itself - Animate layout properties casually (`width`, `height`, `top`, `left`, margins) when transform, FLIP, or grid-based techniques would work -- Use durations over 500ms for feedback—it feels laggy -- Animate without purpose—every animation needs a reason -- Ignore `prefers-reduced-motion`—this is an accessibility violation -- Animate everything—animation fatigue makes interfaces feel exhausting +- Use durations over 500ms for feedback (it feels laggy) +- Animate without purpose (every animation needs a reason) +- Ignore `prefers-reduced-motion` (this is an accessibility violation) +- Animate everything (animation fatigue makes interfaces feel exhausting) - Block interaction during animations unless intentional ## Verify Quality @@ -172,4 +172,4 @@ Test animations thoroughly: - **Doesn't block**: Users can interact during/after animations - **Adds value**: Makes interface clearer or more delightful -Remember: Motion should enhance understanding and provide feedback, not just add decoration. Animate with purpose, respect performance constraints, and always consider accessibility. Great animation is invisible - it just makes everything feel right. +When the motion clarifies state instead of decorating it, hand off to `$impeccable polish` for the final pass. diff --git a/.agents/skills/impeccable/reference/audit.md b/.agents/skills/impeccable/reference/audit.md index 00ac34bc..10f5572f 100644 --- a/.agents/skills/impeccable/reference/audit.md +++ b/.agents/skills/impeccable/reference/audit.md @@ -1,4 +1,4 @@ -Run systematic **technical** quality checks and generate a comprehensive report. Don't fix issues — document them for other commands to address. +Run systematic **technical** quality checks and generate a comprehensive report. Don't fix issues; document them for other commands to address. This is a code-level audit, not a design critique. Check what's measurable and verifiable in the implementation. @@ -83,10 +83,10 @@ Check against ALL the **DON'T** guidelines from the parent impeccable skill (alr ### Detailed Findings by Severity Tag every issue with **P0-P3 severity**: -- **P0 Blocking**: Prevents task completion — fix immediately -- **P1 Major**: Significant difficulty or WCAG AA violation — fix before release -- **P2 Minor**: Annoyance, workaround exists — fix in next pass -- **P3 Polish**: Nice-to-fix, no real user impact — fix if time permits +- **P0 Blocking**: Prevents task completion. Fix immediately +- **P1 Major**: Significant difficulty or WCAG AA violation. Fix before release +- **P2 Minor**: Annoyance, workaround exists. Fix in next pass +- **P3 Polish**: Nice-to-fix, no real user impact. Fix if time permits For each issue, document: - **[P?] Issue name** @@ -105,14 +105,14 @@ Identify recurring problems that indicate systemic gaps rather than one-off mist ### Positive Findings -Note what's working well — good practices to maintain and replicate. +Note what's working well: good practices to maintain and replicate. ## Recommended Actions List recommended commands in priority order (P0 first, then P1, then P2): -1. **[P?] `$command-name`** — Brief description (specific context from audit findings) -2. **[P?] `$command-name`** — Brief description (specific context) +1. **[P?] `$command-name`**: Brief description (specific context from audit findings) +2. **[P?] `$command-name`**: Brief description (specific context) **Rules**: Only recommend commands from: $impeccable adapt, $impeccable animate, $impeccable audit, $impeccable bolder, $impeccable clarify, $impeccable colorize, $impeccable critique, $impeccable delight, $impeccable distill, $impeccable document, $impeccable harden, $impeccable layout, $impeccable onboard, $impeccable optimize, $impeccable overdrive, $impeccable polish, $impeccable quieter, $impeccable shape, $impeccable typeset. Map findings to the most appropriate command. End with `$impeccable polish` as the final step if any fixes were recommended. @@ -131,4 +131,3 @@ After presenting the summary, tell the user: - Forget to prioritize (everything can't be P0) - Report false positives without verification -Remember: You're a technical quality auditor. Document systematically, prioritize ruthlessly, cite specific code locations, and provide clear paths to improvement. diff --git a/.agents/skills/impeccable/reference/bolder.md b/.agents/skills/impeccable/reference/bolder.md index e374312e..25e94d59 100644 --- a/.agents/skills/impeccable/reference/bolder.md +++ b/.agents/skills/impeccable/reference/bolder.md @@ -1,4 +1,4 @@ -Increase visual impact and personality in designs that are too safe, generic, or visually underwhelming, creating more engaging and memorable experiences. +When asked for "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the opposite of bold. Reject them first, then increase visual impact and personality through stronger hierarchy, committed scale, and decisive type. --- @@ -6,7 +6,7 @@ Increase visual impact and personality in designs that are too safe, generic, or Brand: "bolder" means distinctive. Extreme scale, unexpected color, typographic risk, committed POV. -Product: "bolder" rarely means theatrics — those undermine trust. It means stronger hierarchy, clearer weight contrast, one sharper accent, more committed density. The amplification is in clarity, not drama. +Product: "bolder" rarely means theatrics; those undermine trust. It means stronger hierarchy, clearer weight contrast, one sharper accent, more committed density. The amplification is in clarity, not drama. --- @@ -32,7 +32,7 @@ If any of these are unclear from the codebase, STOP and use Codex's structured u **CRITICAL**: "Bolder" doesn't mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random chaos. -**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan/purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold. They're generic. Review ALL the DON'T guidelines from the parent impeccable skill (already loaded in this context) before proceeding. Bold means distinctive, not "more effects." +**WARNING - AI SLOP TRAP**: Review ALL the DON'T guidelines from the parent impeccable skill (already loaded in this context) before proceeding. Bold means distinctive, not "more effects." ## Plan Amplification @@ -57,7 +57,7 @@ Systematically increase impact across these dimensions: ### Color Intensification - **Increase saturation**: Shift to more vibrant, energetic colors (but not neon) -- **Bold palette**: Introduce unexpected color combinations—avoid the purple-blue gradient AI slop +- **Bold palette**: Introduce unexpected color combinations. Avoid the purple-blue gradient AI slop - **Dominant color strategy**: Let one bold color own 60% of the design - **Sharp accents**: High-contrast accent colors that pop - **Tinted neutrals**: Replace pure grays with tinted grays that harmonize with your palette @@ -73,7 +73,7 @@ Systematically increase impact across these dimensions: ### Visual Effects - **Dramatic shadows**: Large, soft shadows for elevation (but not generic drop shadows on rounded rectangles) - **Background treatments**: Mesh patterns, noise textures, geometric patterns, intentional gradients (not purple-to-blue) -- **Texture & depth**: Grain, halftone, duotone, layered elements—NOT glassmorphism (it's overused AI slop) +- **Texture & depth**: Grain, halftone, duotone, layered elements. NOT glassmorphism (it's overused AI slop) - **Borders & frames**: Thick borders, decorative frames, custom shapes (not rounded rectangles with colored border on one side) - **Custom elements**: Illustrative elements, custom icons, decorative details that reinforce brand @@ -81,7 +81,7 @@ Systematically increase impact across these dimensions: - **Entrance choreography**: Staggered, dramatic page load animations with 50-100ms delays - **Scroll effects**: Parallax, reveal animations, scroll-triggered sequences - **Micro-interactions**: Satisfying hover effects, click feedback, state changes -- **Transitions**: Smooth, noticeable transitions using ease-out-quart/quint/expo (not bounce or elastic—they cheapen the effect) +- **Transitions**: Smooth, noticeable transitions using ease-out-quart/quint/expo (not bounce or elastic, which cheapen the effect) ### Composition Boldness - **Hero moments**: Create clear focal points with dramatic treatment @@ -92,7 +92,7 @@ Systematically increase impact across these dimensions: **NEVER**: - Add effects randomly without purpose (chaos ≠ bold) - Sacrifice readability for aesthetics (body text must be readable) -- Make everything bold (then nothing is bold - need contrast) +- Make everything bold (then nothing is bold; you need contrast) - Ignore accessibility (bold design must still meet WCAG standards) - Overwhelm with motion (animation fatigue is real) - Copy trendy aesthetics blindly (bold means distinctive, not derivative) @@ -110,4 +110,4 @@ Ensure amplification maintains usability and coherence: **The test**: If you showed this to someone and said "AI made this bolder," would they believe you immediately? If yes, you've failed. Bold means distinctive, not "more AI effects." -Remember: Bold design is confident design. It takes risks, makes statements, and creates memorable experiences. But bold without strategy is just loud. Be intentional, be dramatic, be unforgettable. +When the result feels right, hand off to `$impeccable polish` for the final pass. diff --git a/.agents/skills/impeccable/reference/brand.md b/.agents/skills/impeccable/reference/brand.md index ab974806..b069f255 100644 --- a/.agents/skills/impeccable/reference/brand.md +++ b/.agents/skills/impeccable/reference/brand.md @@ -1,12 +1,12 @@ # Brand register -When design IS the product: brand sites, landing pages, marketing surfaces, campaign pages, portfolios, long-form content, about pages. The deliverable is the design itself — a visitor's impression is the thing being made. +When design IS the product: brand sites, landing pages, marketing surfaces, campaign pages, portfolios, long-form content, about pages. The deliverable is the design itself; a visitor's impression is the thing being made. -The register spans every genre. A tech brand (Stripe, Linear, Vercel). A luxury brand (a hotel, a fashion house). A consumer product (a restaurant, a travel site, a CPG packaging page). A creative studio, an agency portfolio, a band's album page. They all share the stance — *communicate, not transact* — and diverge wildly in aesthetic. Don't collapse them into a single look. +The register spans every genre. A tech brand (Stripe, Linear, Vercel). A luxury brand (a hotel, a fashion house). A consumer product (a restaurant, a travel site, a CPG packaging page). A creative studio, an agency portfolio, a band's album page. They all share the stance (*communicate, not transact*) and diverge wildly in aesthetic. Don't collapse them into a single look. ## The brand slop test -If someone could look at this and say "AI made that" without hesitation, it's failed. The bar is distinctiveness — a visitor should ask "how was this made?", not "which AI made this?" +If someone could look at this and say "AI made that" without hesitation, it's failed. The bar is distinctiveness; a visitor should ask "how was this made?", not "which AI made this?" Brand isn't a neutral register. AI-generated landing pages have flooded the internet, and average is no longer findable. Restraint without intent now reads as mediocre, not refined. Brand surfaces need a POV, a specific audience, a willingness to risk strangeness. Go big or go home. @@ -18,35 +18,35 @@ Brand isn't a neutral register. AI-generated landing pages have flooded the inte Every project. Never skip. -1. Read the brief. Write three concrete brand-voice words — not "modern" or "elegant," but "warm and mechanical and opinionated" or "calm and clinical and careful." Physical-object words. -2. List the three fonts you'd reach for by reflex. If any appear in the reflex-reject list below, reject them — they are training-data defaults and they create monoculture. -3. Browse a real catalog (Google Fonts, Pangram Pangram, Future Fonts, Adobe Fonts, ABC Dinamo, Klim, Velvetyne) with the three words in mind. Find the font for the brand as a *physical object* — a museum caption, a 1970s terminal manual, a fabric label, a cheap-newsprint children's book, a concert poster, a receipt from a mid-century diner. Reject the first thing that "looks designy." +1. Read the brief. Write three concrete brand-voice words. Not "modern" or "elegant," but "warm and mechanical and opinionated" or "calm and clinical and careful." Physical-object words. +2. List the three fonts you'd reach for by reflex. If any appear in the reflex-reject list below, reject them; they are training-data defaults and they create monoculture. +3. Browse a real catalog (Google Fonts, Pangram Pangram, Future Fonts, Adobe Fonts, ABC Dinamo, Klim, Velvetyne) with the three words in mind. Find the font for the brand as a *physical object*: a museum caption, a 1970s terminal manual, a fabric label, a cheap-newsprint children's book, a concert poster, a receipt from a mid-century diner. Reject the first thing that "looks designy." 4. Cross-check. "Elegant" is not necessarily serif. "Technical" is not necessarily sans. "Warm" is not Fraunces. If the final pick lines up with the original reflex, start over. ### Reflex-reject list -Training-data defaults. Ban list — look further: +Training-data defaults. Ban list. Look further: Fraunces · Newsreader · Lora · Crimson · Crimson Pro · Crimson Text · Playfair Display · Cormorant · Cormorant Garamond · Syne · IBM Plex Mono · IBM Plex Sans · IBM Plex Serif · Space Mono · Space Grotesk · Inter · DM Sans · DM Serif Display · DM Serif Text · Outfit · Plus Jakarta Sans · Instrument Sans · Instrument Serif ### Reflex-reject aesthetic lanes -Parallel to the font list. Currently saturated aesthetic families that have flooded brand surfaces. If a brief lands in one of these lanes without a register reason that *requires* it (a literal magazine, a literal terminal, a literal industrial signage system), it's the second-order training reflex — the trap one tier deeper than picking a Fraunces font. Look further. +Parallel to the font list. Currently saturated aesthetic families that have flooded brand surfaces. If a brief lands in one of these lanes without a register reason that *requires* it (a literal magazine, a literal terminal, a literal industrial signage system), it's the second-order training reflex: the trap one tier deeper than picking a Fraunces font. Look further. - **Editorial-typographic.** Display serif (often italic) + small mono labels + ruled separators + monochromatic restraint. Klim-influenced, magazine-cover affectation. By 2026, every Stripe-adjacent and Notion-adjacent brand has landed here. The fingerprint: three rule-separated columns, an italic Fraunces / Recoleta / Newsreader headline, lowercase track-spaced metadata, no imagery. (More entries land here on the same cadence the font list updates. Brutalist-utility and acid-maximalism may join when they saturate. Removing entries when they fall back below saturation is also fine.) -The reflex-reject lists apply to **new design choices**. When the existing brand has already committed to a font or a lane as part of its identity, identity-preservation wins — variants on an existing surface don't second-guess what's already shipping. The reflex-reject lists are for greenfield decisions and for departure-mode variants in [live.md](live.md). +The reflex-reject lists apply to **new design choices**. When the existing brand has already committed to a font or a lane as part of its identity, identity-preservation wins; variants on an existing surface don't second-guess what's already shipping. The reflex-reject lists are for greenfield decisions and for departure-mode variants in [live.md](live.md). ### Pairing and voice -Distinctive + refined is the goal — the specific shape depends on the brand: +Distinctive + refined is the goal. The specific shape depends on the brand: - **Editorial / long-form / luxury**: display serif + sans body (a magazine shape). - **Tech / dev tools / fintech**: one committed sans, usually; custom-tight tracking, strong weight contrast inside a single family. - **Consumer / food / travel**: warmer pairings, often a humanist sans plus a script or display serif. -- **Creative studios / agencies**: rule-breaking welcome — mono-only, or display-only, or custom-drawn type as voice. +- **Creative studios / agencies**: rule-breaking welcome. Mono-only, or display-only, or custom-drawn type as voice. Two families minimum is the rule *only* when the voice needs it. A single well-chosen family with committed weight/size contrast is stronger than a timid display+body pair. @@ -60,7 +60,7 @@ Light text on dark backgrounds: add 0.05–0.1 to line-height. Light type reads ## Color -Brand surfaces have permission for Committed, Full palette, and Drenched strategies. Use them. A single saturated color spread across a hero is not excess — it's voice. A beige-and-muted-slate landing page ignores the register. +Brand surfaces have permission for Committed, Full palette, and Drenched strategies. Use them. A single saturated color spread across a hero is not excess; it's voice. A beige-and-muted-slate landing page ignores the register. - Name a real reference before picking a strategy. "Klim Type Foundry #ff4500 orange drench", "Stripe purple-on-white restraint", "Liquid Death acid-green full palette", "Mailchimp yellow full palette", "Condé Nast Traveler muted navy restraint", "Vercel pure black monochrome". Unnamed ambition becomes beige. - Palette IS voice. A calm brand and a restless brand should not share palette mechanics. @@ -70,10 +70,10 @@ Brand surfaces have permission for Committed, Full palette, and Drenched strateg ## Layout - Asymmetric compositions are one option. Break the grid intentionally for emphasis. -- Fluid spacing with `clamp()` that breathes on larger viewports. Vary for rhythm — generous separations, tight groupings. -- Alternative: a strict, visible grid as the voice (brutalist / Swiss / tech-spec aesthetics). Either asymmetric or rigorously-gridded can be "designed" — the failure mode is splitting the difference into a generic centered stack. +- Fluid spacing with `clamp()` that breathes on larger viewports. Vary for rhythm: generous separations, tight groupings. +- Alternative: a strict, visible grid as the voice (brutalist / Swiss / tech-spec aesthetics). Either asymmetric or rigorously-gridded can be "designed"; the failure mode is splitting the difference into a generic centered stack. - Don't default to centering everything. Left-aligned with asymmetric layouts feels more designed; a strict grid reads as confident structure. A centered-stack hero with icon-title-subtitle cards reads as template. -- When cards ARE the right affordance, use `grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))` — breakpoint-free responsiveness. +- When cards ARE the right affordance, use `grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))` for breakpoint-free responsiveness. ## Imagery @@ -81,16 +81,16 @@ Brand surfaces lean on imagery. A restaurant, hotel, magazine, or product landin **When the brief implies imagery (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product), you must ship imagery.** Zero images is a bug, not a design choice. "Restraint" is not an excuse. -- **For greenfield work without local assets, use stock imagery** — Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. +- **For greenfield work without local assets, use stock imagery.** Unsplash is the default. The URL shape is `https://images.unsplash.com/photo-{id}?auto=format&fit=crop&w=1600&q=80`. Pick real Unsplash photo IDs you're confident exist (`photo-1559339352-11d035aa65de`, `photo-1590490360182-c33d57733427`, etc.); if unsure, pick fewer photos but don't substitute colored `
` placeholders. - **Search for the brand's physical object**, not the generic category: "handmade pasta on a scratched wooden table" beats "Italian food"; "cypress trees above a limestone hotel facade at dusk" beats "luxury hotel". - **One decisive photo beats five mediocre ones.** Hero imagery should commit to a mood; padding with more stock doesn't rescue an indecisive one. - **Alt text is part of the voice.** "Coastal fettuccine, hand-cut, served on the terrace" beats "pasta dish". -Tech / dev-tool brands are the exception where zero imagery can be correct — a developer landing page often carries its voice through typography, code samples, diagrams. Know which kind of brand you're working on. +Tech / dev-tool brands are the exception where zero imagery can be correct; a developer landing page often carries its voice through typography, code samples, diagrams. Know which kind of brand you're working on. ## Motion -- One well-orchestrated page-load with staggered reveals beats scattered micro-interactions — when the brand invites it. Tech-minimal brands often skip entrance motion entirely; the restraint is the voice. +- One well-orchestrated page-load with staggered reveals beats scattered micro-interactions, when the brand invites it. Tech-minimal brands often skip entrance motion entirely; the restraint is the voice. - For collapsing/expanding sections, transition `grid-template-rows` rather than `height`. ## Brand bans (on top of the shared absolute bans) @@ -110,5 +110,5 @@ Brand can afford things product can't. Take them. - Ambitious first-load motion. Reveals, scroll-triggered transitions, typographic choreography. - Single-purpose viewports. One dominant idea per fold, long scroll, deliberate pacing. - Typographic risk. Enormous display type, unexpected italic cuts, mixed cases, hand-drawn headlines, a single oversize word as a hero. -- Unexpected color strategies. Palette IS voice — a calm brand and a restless brand should not share palette mechanics. +- Unexpected color strategies. Palette IS voice; a calm brand and a restless brand should not share palette mechanics. - Art direction per section. Different sections can have different visual worlds if the narrative demands it. Consistency of voice beats consistency of treatment. diff --git a/.agents/skills/impeccable/reference/clarify.md b/.agents/skills/impeccable/reference/clarify.md index dc116e74..07b9d8d2 100644 --- a/.agents/skills/impeccable/reference/clarify.md +++ b/.agents/skills/impeccable/reference/clarify.md @@ -1,6 +1,6 @@ > **Additional context needed**: audience technical level and users' mental state in context. -Identify and improve unclear, confusing, or poorly written interface text to make the product easier to understand and use. +Find the unclear, confusing, or poorly written interface text and rewrite it. Vague copy creates support tickets and abandonment; specific copy gets users through the task. --- @@ -146,7 +146,7 @@ Every piece of copy should follow these rules: 2. **Be concise**: Cut unnecessary words (but don't sacrifice clarity) 3. **Be active**: "Save changes" not "Changes will be saved" 4. **Be human**: "Oops, something went wrong" not "System error encountered" -5. **Be helpful**: Tell users what to do, not just what happened +5. **Tell users what to do**, not just what happened 6. **Be consistent**: Use same terms throughout (don't vary for variety) **NEVER**: @@ -171,4 +171,4 @@ Test that copy improvements work: - **Consistency**: Does it match terminology elsewhere? - **Tone**: Is it appropriate for the situation? -Remember: You're a clarity expert with excellent communication skills. Write like you're explaining to a smart friend who's unfamiliar with the product. Be clear, be helpful, be human. +When the copy reads cleanly, hand off to `$impeccable polish` for the final pass. diff --git a/.agents/skills/impeccable/reference/cognitive-load.md b/.agents/skills/impeccable/reference/cognitive-load.md index 313df166..48f8ad58 100644 --- a/.agents/skills/impeccable/reference/cognitive-load.md +++ b/.agents/skills/impeccable/reference/cognitive-load.md @@ -6,17 +6,17 @@ Cognitive load is the total mental effort required to use an interface. Overload ## Three Types of Cognitive Load -### Intrinsic Load — The Task Itself +### Intrinsic Load: The Task Itself Complexity inherent to what the user is trying to do. You can't eliminate this, but you can structure it. **Manage it by**: - Breaking complex tasks into discrete steps - Providing scaffolding (templates, defaults, examples) -- Progressive disclosure — show what's needed now, hide the rest +- Progressive disclosure: show what's needed now, hide the rest - Grouping related decisions together -### Extraneous Load — Bad Design -Mental effort caused by poor design choices. **Eliminate this ruthlessly** — it's pure waste. +### Extraneous Load: Bad Design +Mental effort caused by poor design choices. **Eliminate this ruthlessly.** It's pure waste. **Common sources**: - Confusing navigation that requires mental mapping @@ -25,8 +25,8 @@ Mental effort caused by poor design choices. **Eliminate this ruthlessly** — i - Inconsistent patterns that prevent learning - Unnecessary steps between user intent and result -### Germane Load — Learning Effort -Mental effort spent building understanding. This is *good* cognitive load — it leads to mastery. +### Germane Load: Learning Effort +Mental effort spent building understanding. This is *good* cognitive load; it leads to mastery. **Support it by**: - Progressive disclosure that reveals complexity gradually @@ -58,9 +58,9 @@ Evaluate the interface against these 8 items: **Humans can hold ≤4 items in working memory at once** (Miller's Law revised by Cowan, 2001). At any decision point, count the number of distinct options, actions, or pieces of information a user must simultaneously consider: -- **≤4 items**: Within working memory limits — manageable -- **5–7 items**: Pushing the boundary — consider grouping or progressive disclosure -- **8+ items**: Overloaded — users will skip, misclick, or abandon +- **≤4 items**: Within working memory limits, manageable +- **5–7 items**: Pushing the boundary; consider grouping or progressive disclosure +- **8+ items**: Overloaded; users will skip, misclick, or abandon **Practical applications**: - Navigation menus: ≤5 top-level items (group the rest under clear categories) @@ -90,7 +90,7 @@ At any decision point, count the number of distinct options, actions, or pieces **Fix**: Use plain language. If domain terms are unavoidable, define them inline. ### 5. The Visual Noise Floor -**Problem**: Every element has the same visual weight — nothing stands out. +**Problem**: Every element has the same visual weight; nothing stands out. **Fix**: Establish clear hierarchy: one primary element, 2–3 secondary, everything else muted. ### 6. The Inconsistent Pattern diff --git a/.agents/skills/impeccable/reference/color-and-contrast.md b/.agents/skills/impeccable/reference/color-and-contrast.md index 88a15cce..110c2ee4 100644 --- a/.agents/skills/impeccable/reference/color-and-contrast.md +++ b/.agents/skills/impeccable/reference/color-and-contrast.md @@ -2,11 +2,11 @@ ## Color Spaces: Use OKLCH -**Stop using HSL.** Use OKLCH (or LCH) instead. It's perceptually uniform, meaning equal steps in lightness *look* equal—unlike HSL where 50% lightness in yellow looks bright while 50% in blue looks dark. +**Stop using HSL.** Use OKLCH (or LCH) instead. It's perceptually uniform, meaning equal steps in lightness *look* equal, unlike HSL where 50% lightness in yellow looks bright while 50% in blue looks dark. -The OKLCH function takes three components: `oklch(lightness chroma hue)` where lightness is 0-100%, chroma is roughly 0-0.4, and hue is 0-360. To build a primary color and its lighter / darker variants, hold the chroma+hue roughly constant and vary the lightness — but **reduce chroma as you approach white or black**, because high chroma at extreme lightness looks garish. +The OKLCH function takes three components: `oklch(lightness chroma hue)` where lightness is 0-100%, chroma is roughly 0-0.4, and hue is 0-360. To build a primary color and its lighter / darker variants, hold the chroma+hue roughly constant and vary the lightness, but **reduce chroma as you approach white or black**, because high chroma at extreme lightness looks garish. -The hue you pick is a brand decision and should not come from a default. Do not reach for blue (hue 250) or warm orange (hue 60) by reflex — those are the dominant AI-design defaults, not the right answer for any specific brand. +The hue you pick is a brand decision and should not come from a default. Do not reach for blue (hue 250) or warm orange (hue 60) by reflex; those are the dominant AI-design defaults, not the right answer for any specific brand. ## Building Functional Palettes @@ -36,8 +36,8 @@ A complete system needs: This rule is about **visual weight**, not pixel count: - **60%**: Neutral backgrounds, white space, base surfaces -- **30%**: Secondary colors—text, borders, inactive states -- **10%**: Accent—CTAs, highlights, focus states +- **30%**: Secondary colors: text, borders, inactive states +- **10%**: Accent: CTAs, highlights, focus states The common mistake: using the accent color everywhere because it's "the brand color." Accent colors work *because* they're rare. Overuse kills their power. @@ -59,15 +59,15 @@ The common mistake: using the accent color everywhere because it's "the brand co These commonly fail contrast or cause readability issues: - Light gray text on white (the #1 accessibility fail) -- **Gray text on any colored background**—gray looks washed out and dead on color. Use a darker shade of the background color, or transparency -- Red text on green background (or vice versa)—8% of men can't distinguish these +- **Gray text on any colored background**: gray looks washed out and dead on color. Use a darker shade of the background color, or transparency +- Red text on green background (or vice versa): 8% of men can't distinguish these - Blue text on red background (vibrates visually) - Yellow text on white (almost always fails) - Thin light text on images (unpredictable contrast) ### Never Use Pure Gray or Pure Black -Pure gray (`oklch(50% 0 0)`) and pure black (`#000`) don't exist in nature—real shadows and surfaces always have a color cast. Even a chroma of 0.005-0.01 is enough to feel natural without being obviously tinted. (See tinted neutrals example above.) +Pure gray (`oklch(50% 0 0)`) and pure black (`#000`) don't exist in nature; real shadows and surfaces always have a color cast. Even a chroma of 0.005-0.01 is enough to feel natural without being obviously tinted. (See tinted neutrals example above.) ### Testing @@ -88,13 +88,13 @@ You can't just swap colors. Dark mode requires different design decisions: | Shadows for depth | Lighter surfaces for depth (no shadows) | | Dark text on light | Light text on dark (reduce font weight) | | Vibrant accents | Desaturate accents slightly | -| White backgrounds | Never pure black—use dark gray (oklch 12-18%) | +| White backgrounds | Never pure black; use dark gray (oklch 12-18%) | -In dark mode, depth comes from surface lightness, not shadow. Build a 3-step surface scale where higher elevations are lighter (e.g. 15% / 20% / 25% lightness). Use the SAME hue and chroma as your brand color (whatever it is for THIS project — do not reach for blue) and only vary the lightness. Reduce body text weight slightly (e.g. 350 instead of 400) because light text on dark reads as heavier than dark text on light. +In dark mode, depth comes from surface lightness, not shadow. Build a 3-step surface scale where higher elevations are lighter (e.g. 15% / 20% / 25% lightness). Use the SAME hue and chroma as your brand color (whatever it is for THIS project; do not reach for blue) and only vary the lightness. Reduce body text weight slightly (e.g. 350 instead of 400) because light text on dark reads as heavier than dark text on light. ### Token Hierarchy -Use two layers: primitive tokens (`--blue-500`) and semantic tokens (`--color-primary: var(--blue-500)`). For dark mode, only redefine the semantic layer—primitives stay the same. +Use two layers: primitive tokens (`--blue-500`) and semantic tokens (`--color-primary: var(--blue-500)`). For dark mode, only redefine the semantic layer; primitives stay the same. ## Alpha Is A Design Smell diff --git a/.agents/skills/impeccable/reference/colorize.md b/.agents/skills/impeccable/reference/colorize.md index 3acc1a58..a6ddfb29 100644 --- a/.agents/skills/impeccable/reference/colorize.md +++ b/.agents/skills/impeccable/reference/colorize.md @@ -1,14 +1,14 @@ > **Additional context needed**: existing brand colors. -Strategically introduce color to designs that are too monochromatic, gray, or lacking in visual warmth and personality. +Replace timid grayscale or single-accent designs with a strategic palette: pick a color strategy, choose a hue family that fits the brand, then apply color with intent. More color ≠ better. Strategic color beats rainbow vomit. --- ## Register -Brand: palette IS voice. Pick a color strategy first per SKILL.md (Restrained / Committed / Full palette / Drenched) and follow its dosage. Committed, Full palette, and Drenched deliberately exceed the ≤10% rule — that rule is Restrained only. Unexpected combinations are allowed; a dominant color can own the page when the chosen strategy calls for it. +Brand: palette IS voice. Pick a color strategy first per SKILL.md (Restrained / Committed / Full palette / Drenched) and follow its dosage. Committed, Full palette, and Drenched deliberately exceed the ≤10% rule; that rule is Restrained only. Unexpected combinations are allowed; a dominant color can own the page when the chosen strategy calls for it. -Product: semantic-first and almost always Restrained. Accent color is reserved for primary action, current selection, and state indicators — not decoration. Every color has a consistent meaning across every screen. +Product: semantic-first and almost always Restrained. Accent color is reserved for primary action, current selection, and state indicators. Not decoration. Every color has a consistent meaning across every screen. --- @@ -81,13 +81,13 @@ Add color systematically across these dimensions: - **Comparison**: Color coding for different datasets or timeframes ### Borders & Accents -- **Hairline borders**: 1px colored borders on full perimeter (not side-stripes — see the absolute ban on `border-left/right > 1px`) +- **Hairline borders**: 1px colored borders on full perimeter (not side-stripes; see the absolute ban on `border-left/right > 1px`) - **Underlines**: Color underlines for emphasis or active states - **Dividers**: Subtle colored dividers instead of gray lines - **Focus rings**: Colored focus indicators matching brand - **Surface tints**: A 4-8% background wash of the accent color instead of a stripe -**NEVER**: `border-left` or `border-right` greater than 1px as a colored accent stripe. This is one of the three absolute bans in the parent skill. If you want to mark a card as "active" or "warning", use a full hairline border, a background tint, a leading glyph, or a numbered prefix — not a side stripe. +**NEVER**: `border-left` or `border-right` greater than 1px as a colored accent stripe. This is one of the three absolute bans in the parent skill. If you want to mark a card as "active" or "warning", use a full hairline border, a background tint, a leading glyph, or a numbered prefix. Not a side stripe. ### Typography Color - **Colored headings**: Use brand colors for section headings (maintain contrast) @@ -123,8 +123,8 @@ Ensure color addition improves rather than overwhelms: **NEVER**: - Use every color in the rainbow (choose 2-4 colors beyond neutrals) - Apply color randomly without semantic meaning -- Put gray text on colored backgrounds—it looks washed out; use a darker shade of the background color or transparency instead -- Use pure gray for neutrals—add subtle color tint (warm or cool) for sophistication +- Put gray text on colored backgrounds. It looks washed out; use a darker shade of the background color or transparency instead +- Use pure gray for neutrals. Add subtle color tint (warm or cool) for depth - Use pure black (`#000`) or pure white (`#fff`) for large areas - Violate WCAG contrast requirements - Use color as the only indicator (accessibility issue) @@ -141,11 +141,11 @@ Test that colorization improves the experience: - **Still accessible**: Do all color combinations meet WCAG standards? - **Not overwhelming**: Is color balanced and purposeful? -Remember: Color is emotional and powerful. Use it to create warmth, guide attention, communicate meaning, and express personality. But restraint and strategy matter more than saturation and variety. Be colorful, but be intentional. +When the palette earns its place, hand off to `$impeccable polish` for the final pass. ## Live-mode signature params -When invoked from live mode, each variant MUST declare a `color-amount` param so the user can dial between a restrained accent and a drenched surface without regeneration. Author the variant's CSS against `var(--p-color-amount, 0.5)` — typically as the alpha multiplier on backgrounds, or as a scaling factor on the chroma axis in an OKLCH expression. 0 = neutral/monochrome, 1 = full saturation / dominant coverage. +When invoked from live mode, each variant MUST declare a `color-amount` param so the user can dial between a restrained accent and a drenched surface without regeneration. Author the variant's CSS against `var(--p-color-amount, 0.5)`, typically as the alpha multiplier on backgrounds, or as a scaling factor on the chroma axis in an OKLCH expression. 0 = neutral/monochrome, 1 = full saturation / dominant coverage. ```json {"id":"color-amount","kind":"range","min":0,"max":1,"step":0.05,"default":0.5,"label":"Color amount"} diff --git a/.agents/skills/impeccable/reference/critique.md b/.agents/skills/impeccable/reference/critique.md index 3ea21398..4e9b73db 100644 --- a/.agents/skills/impeccable/reference/critique.md +++ b/.agents/skills/impeccable/reference/critique.md @@ -2,7 +2,7 @@ ### Gather Assessments -Launch two independent assessments. **Neither may see the other's output** — this isolation is what makes the combined score honest. Running both in one head silently anchors them to each other; do not shortcut it for cost, speed, or context-size reasons. +Launch two independent assessments. **Neither may see the other's output.** This isolation is what makes the combined score honest. Running both in one head silently anchors them to each other; do not shortcut it for cost, speed, or context-size reasons. Delegate each assessment to a separate sub-agent (Claude Code's `Agent` tool, Codex's subagent spawning, etc.). Each returns structured findings as text. Do NOT output findings to the user yet. @@ -52,7 +52,7 @@ npx impeccable --json [--fast] [target] - For 500+ files, narrow scope or ask the user - Exit code 0 = clean, 2 = findings -**Browser visualization** — **required** when browser automation tools are available AND the target is a viewable page. The `[Human]` overlay tab is the user-facing deliverable; the critique is incomplete without it. Skip only if the target is not a viewable page (CSS-only file, non-browser target). +**Browser visualization**: **required** when browser automation tools are available AND the target is a viewable page. The `[Human]` overlay tab is the user-facing deliverable; the critique is incomplete without it. Skip only if the target is not a viewable page (CSS-only file, non-browser target). The overlay is a **visual aid for the user**. It highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically. @@ -160,7 +160,7 @@ Provocative questions that might unlock better solutions: - Be direct. Vague feedback wastes everyone's time. - Be specific. "The submit button," not "some elements." - Say what's wrong AND why it matters to users. -- Give concrete suggestions, not just "consider exploring..." +- Give concrete suggestions. Cut "consider exploring..." entirely. - Prioritize ruthlessly. If everything is important, nothing is. - Don't soften criticism. Developers need honest feedback to ship great design. diff --git a/.agents/skills/impeccable/reference/delight.md b/.agents/skills/impeccable/reference/delight.md index 21fcd568..b3196705 100644 --- a/.agents/skills/impeccable/reference/delight.md +++ b/.agents/skills/impeccable/reference/delight.md @@ -1,12 +1,12 @@ > **Additional context needed**: what's appropriate for the domain (playful vs professional vs quirky vs elegant). -Identify opportunities to add moments of joy, personality, and unexpected polish that transform functional interfaces into delightful experiences. +Find the moments where personality and unexpected polish would turn a functional interface into one users remember and tell other people about. Add only where the moment earns it; delight everywhere reads as noise. --- ## Register -Brand: delight can be distributed — copy voice, section transitions, discovery rewards, seasonal touches, personality across the whole surface. +Brand: delight can be distributed across copy voice, section transitions, discovery rewards, seasonal touches, personality across the whole surface. Product: delight at specific moments, not pages. Completion, first-time actions, error recovery, milestone crossings. Reliability and consistency carry the rest of the experience; delight pushed everywhere reads as noise. @@ -236,14 +236,14 @@ Add personality and joy through these methods: - Countdown with encouraging messages ``` -Loading messages — write ones specific to your product, not generic AI filler: +Loading messages: write ones specific to your product, not generic AI filler: - "Crunching your latest numbers..." - "Syncing with your team's changes..." - "Preparing your dashboard..." - "Checking for updates since yesterday..." ``` -**WARNING**: Avoid cliched loading messages like "Herding pixels", "Teaching robots to dance", "Consulting the magic 8-ball", "Counting backwards from infinity". These are AI-slop copy — instantly recognizable as machine-generated. Write messages that are specific to what your product actually does. +**WARNING**: Avoid cliched loading messages like "Herding pixels", "Teaching robots to dance", "Consulting the magic 8-ball", "Counting backwards from infinity". These are AI-slop copy, instantly recognizable as machine-generated. Write messages that are specific to what your product actually does. ### Celebration Moments @@ -299,4 +299,4 @@ Test that delight actually delights: - **Appropriate**: Matches brand and context - **Accessible**: Works with reduced motion, screen readers -Remember: Delight is the difference between a tool and an experience. Add personality, surprise users positively, and create moments worth sharing. But always respect usability - delight should enhance, never obstruct. +When the moments feel earned, hand off to `$impeccable polish` for the final pass. diff --git a/.agents/skills/impeccable/reference/distill.md b/.agents/skills/impeccable/reference/distill.md index 2779b848..2ac85043 100644 --- a/.agents/skills/impeccable/reference/distill.md +++ b/.agents/skills/impeccable/reference/distill.md @@ -1,4 +1,4 @@ -Remove unnecessary complexity from designs, revealing the essential elements and creating clarity through ruthless simplification. +Strip a design to its essence. Remove anything that doesn't earn its place: redundant elements, repeated information, decorative noise, cosmetic complexity. --- @@ -23,7 +23,7 @@ Analyze what makes the design feel complex or cluttered: If any of these are unclear from the codebase, STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. -**CRITICAL**: Simplicity is not about removing features - it's about removing obstacles between users and their goals. Every element should justify its existence. +**CRITICAL**: Simplicity is not about removing features. It's about removing obstacles between users and their goals. Every element should justify its existence. ## Plan Simplification @@ -51,7 +51,7 @@ Systematically remove complexity across these dimensions: - **Reduce color palette**: Use 1-2 colors plus neutrals, not 5-7 colors - **Limit typography**: One font family, 3-4 sizes maximum, 2-3 weights - **Remove decorations**: Eliminate borders, shadows, backgrounds that don't serve hierarchy or function -- **Flatten structure**: Reduce nesting, remove unnecessary containers—never nest cards inside cards +- **Flatten structure**: Reduce nesting, remove unnecessary containers; never nest cards inside cards - **Remove unnecessary cards**: Cards aren't needed for basic layout; use spacing and alignment instead - **Consistent spacing**: Use one spacing scale, remove arbitrary gaps @@ -108,4 +108,4 @@ If you removed features or options: - Consider if they need alternative access points - Note any user feedback to monitor -Remember: You have great taste and judgment. Simplification is an act of confidence - knowing what to keep and courage to remove the rest. As Antoine de Saint-Exupéry said: "Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away." +When the cuts feel right, hand off to `$impeccable polish` for the final pass. As Antoine de Saint-Exupéry put it: "Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away." diff --git a/.agents/skills/impeccable/reference/document.md b/.agents/skills/impeccable/reference/document.md index 9aba932a..12e9a02d 100644 --- a/.agents/skills/impeccable/reference/document.md +++ b/.agents/skills/impeccable/reference/document.md @@ -44,7 +44,7 @@ Rules that matter: - **Token refs** use `{path.to.token}` (e.g. `{colors.primary}`, `{rounded.md}`). Components may reference primitives; primitives may not reference each other. - **Stitch validates colors as hex sRGB only** (`#RGB` / `#RGBA` / `#RRGGBB` / `#RRGGBBAA`); OKLCH/HSL/P3 trigger a linter warning, not a hard error. YAML accepts the string either way and our own parser is format-agnostic. Choose based on project posture: (a) if the project has an "OKLCH-only" doctrine or uses Display-P3 values that don't round-trip through sRGB, put OKLCH directly in the frontmatter and accept the Stitch linter warning; (b) if the project wants strict Stitch compliance or plans to use their Tailwind/DTCG export pipeline, put hex in the frontmatter and keep OKLCH in prose as the canonical reference. Never split the source of truth without explicit reason. -- **Component sub-tokens** are limited to 8 props: `backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`, `height`, `width`. Shadows, motion, focus rings, backdrop-filter — none of those fit. Carry them in the sidecar (Step 4b). +- **Component sub-tokens** are limited to 8 props: `backgroundColor`, `textColor`, `typography`, `rounded`, `padding`, `size`, `height`, `width`. Shadows, motion, focus rings, backdrop-filter: none of those fit. Carry them in the sidecar (Step 4b). - **Scale keys are open-ended.** Use whatever names the project already uses (`warm-ash-cream`, `surface-container-low`). Don't rename to Material defaults. - **Variants are naming convention, not schema.** `button-primary` / `button-primary-hover` / `button-primary-active` as sibling keys. @@ -57,7 +57,7 @@ Rules that matter: 5. `## Components` 6. `## Do's and Don'ts` -Optional evocative subtitles are allowed in the form `## 2. Colors: The [Name] Palette` — Stitch's own outputs do this — but the literal word in each header (Overview, Colors, Typography, Elevation, Components, Do's and Don'ts) must be present. Do NOT add extra top-level sections (Layout Principles, Responsive Behavior, Motion, Agent Prompt Guide). Fold that content into the six spec sections where it naturally belongs. +Optional evocative subtitles are allowed in the form `## 2. Colors: The [Name] Palette` (Stitch's own outputs do this), but the literal word in each header (Overview, Colors, Typography, Elevation, Components, Do's and Don'ts) must be present. Do NOT add extra top-level sections (Layout Principles, Responsive Behavior, Motion, Agent Prompt Guide). Fold that content into the six spec sections where it naturally belongs. ## When to run @@ -73,7 +73,7 @@ If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user - **Scan mode** (default): the project has design tokens, components, or rendered output. Extract, then confirm descriptive language. Use when there's code to analyze. - **Seed mode**: the project is pre-implementation (fresh teach, nothing built yet). Interview for five high-level answers, write a minimal DESIGN.md marked ``. Re-run in scan mode once there's code. -Decide by scanning first (Scan mode Step 1). If the scan finds no tokens, no component files, and no rendered site, offer seed mode — don't silently switch. `$impeccable document --seed` forces seed mode regardless of code presence. +Decide by scanning first (Scan mode Step 1). If the scan finds no tokens, no component files, and no rendered site, offer seed mode; don't silently switch. `$impeccable document --seed` forces seed mode regardless of code presence. ## Scan mode (approach C: auto-extract, then confirm descriptive language) @@ -81,29 +81,29 @@ Decide by scanning first (Scan mode Step 1). If the scan finds no tokens, no com Search the codebase in priority order: -1. **CSS custom properties** — grep for `--color-`, `--font-`, `--spacing-`, `--radius-`, `--shadow-`, `--ease-`, `--duration-` declarations in CSS files (usually `src/styles/`, `public/css/`, `app/globals.css`, etc.). Record name, value, and the file it's defined in. -2. **Tailwind config** — if `tailwind.config.{js,ts,mjs}` exists, read the `theme.extend` block for colors, fontFamily, spacing, borderRadius, boxShadow. -3. **CSS-in-JS theme files** — styled-components, emotion, vanilla-extract, stitches: look for `theme.ts`, `tokens.ts`, or equivalent. -4. **Design token files** — `tokens.json`, `design-tokens.json`, Style Dictionary output, W3C token community group format. -5. **Component library** — scan the main button, card, input, navigation, dialog components. Note their variant APIs and default styles. -6. **Global stylesheet** — the root CSS file usually has the base typography and color assignments. -7. **Visible rendered output** — if browser automation tools are available, load the live site and sample computed styles from key elements (body, h1, a, button, .card). This catches values that tokens miss. +1. **CSS custom properties**: grep for `--color-`, `--font-`, `--spacing-`, `--radius-`, `--shadow-`, `--ease-`, `--duration-` declarations in CSS files (usually `src/styles/`, `public/css/`, `app/globals.css`, etc.). Record name, value, and the file it's defined in. +2. **Tailwind config**: if `tailwind.config.{js,ts,mjs}` exists, read the `theme.extend` block for colors, fontFamily, spacing, borderRadius, boxShadow. +3. **CSS-in-JS theme files**: styled-components, emotion, vanilla-extract, stitches; look for `theme.ts`, `tokens.ts`, or equivalent. +4. **Design token files**: `tokens.json`, `design-tokens.json`, Style Dictionary output, W3C token community group format. +5. **Component library**: scan the main button, card, input, navigation, dialog components. Note their variant APIs and default styles. +6. **Global stylesheet**: the root CSS file usually has the base typography and color assignments. +7. **Visible rendered output**: if browser automation tools are available, load the live site and sample computed styles from key elements (body, h1, a, button, .card). This catches values that tokens miss. ### Step 2: Auto-extract what can be auto-extracted Build a structured draft from the discovered tokens. For each token class: -- **Colors**: Group into Primary / Secondary / Tertiary / Neutral (the Material-derived roles Stitch uses). If the project only has one accent, express it as Primary + Neutral — omit Secondary and Tertiary rather than inventing them. +- **Colors**: Group into Primary / Secondary / Tertiary / Neutral (the Material-derived roles Stitch uses). If the project only has one accent, express it as Primary + Neutral; omit Secondary and Tertiary rather than inventing them. - **Typography**: Map observed sizes and weights to the Material hierarchy (display / headline / title / body / label). Note font-family stacks and the scale ratio. -- **Elevation**: Catalogue the shadow vocabulary. If the project is flat and uses tonal layering instead, that's a valid answer — state it explicitly. +- **Elevation**: Catalogue the shadow vocabulary. If the project is flat and uses tonal layering instead, that's a valid answer; state it explicitly. - **Components**: For each common component (button, card, input, chip, list item, tooltip, nav), extract shape (radius), color assignment, hover/focus treatment, internal padding. - **Spacing + layout**: Fold into Overview or relevant Components. The spec does NOT have a Layout section. ### Step 2b: Stage the frontmatter -From the auto-extracted tokens, draft the YAML frontmatter now (you'll write it at the top of DESIGN.md in Step 4). This is the machine-readable layer — what the live panel and Stitch's linter consume. +From the auto-extracted tokens, draft the YAML frontmatter now (you'll write it at the top of DESIGN.md in Step 4). This is the machine-readable layer: what the live panel and Stitch's linter consume. -- **Colors**: one entry per extracted color. Key = descriptive slug (`warm-ash-cream`, `editorial-magenta`, not `blue-800`). Value = whichever format the project treats as canonical (OKLCH or hex — see the frontmatter rules above). Don't split the source of truth: one format in the frontmatter, don't redefine the same token in prose with a different value. +- **Colors**: one entry per extracted color. Key = descriptive slug (`warm-ash-cream`, `editorial-magenta`, not `blue-800`). Value = whichever format the project treats as canonical (OKLCH or hex; see the frontmatter rules above). Don't split the source of truth: one format in the frontmatter, don't redefine the same token in prose with a different value. - **Typography**: one entry per role (`display`, `headline`, `title`, `body`, `label`). Typography is an object; include only the props that are real for the project (`fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `fontFeature`, `fontVariation`). - **Rounded / Spacing**: whatever scale steps the project actually uses, keyed by whatever scale name the project uses (`sm` / `md` / `lg`, or `surface-sm`, or numeric steps). - **Components**: one entry per variant (`button-primary`, `button-primary-hover`, `button-ghost`). Reference primitives via `{colors.X}`, `{rounded.Y}`. If a variant needs a property Stitch's 8-prop set doesn't cover (shadow, focus ring, backdrop-filter), carry the full snippet in the sidecar instead. @@ -149,7 +149,7 @@ colors: ### Primary - **[Descriptive Name]** (#HEX / oklch(...)): [Where and why this color is used. Be specific about context, not just role.] -### Secondary (optional — omit if the project has only one accent) +### Secondary (optional; omit if the project has only one accent) - **[Descriptive Name]** (#HEX): [Role.] ### Tertiary (optional) @@ -160,7 +160,7 @@ colors: - [...] ### Named Rules (optional, powerful) -**The [Rule Name] Rule.** [Short, forceful prohibition or doctrine — e.g. "The One Voice Rule. The primary accent is used on ≤10% of any given screen. Its rarity is the point."] +**The [Rule Name] Rule.** [Short, forceful prohibition or doctrine, e.g. "The One Voice Rule. The primary accent is used on ≤10% of any given screen. Its rarity is the point."] ## 3. Typography @@ -171,7 +171,7 @@ colors: **Character:** [1-2 sentence personality description of the pairing.] ### Hierarchy -- **Display** ([weight], [size/clamp], [line-height]): [Purpose — where it appears.] +- **Display** ([weight], [size/clamp], [line-height]): [Purpose; where it appears.] - **Headline** ([weight], [size], [line-height]): [Purpose.] - **Title** ([weight], [size], [line-height]): [Purpose.] - **Body** ([weight], [size], [line-height]): [Purpose. Include max line length like 65–75ch if relevant.] @@ -214,25 +214,25 @@ For each component, lead with a short character line, then specify shape, color ### Inputs / Fields - **Style:** [stroke, background, radius] -- **Focus:** [treatment — glow, border shift, etc.] +- **Focus:** [treatment, e.g. glow, border shift, etc.] - **Error / Disabled:** [if applicable] ### Navigation - **Style, typography, default/hover/active states, mobile treatment.** -### [Signature Component] (optional — if the project has a distinctive custom component worth documenting) +### [Signature Component] (optional; if the project has a distinctive custom component worth documenting) [Description.] ## 6. Do's and Don'ts -Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific — include exact colors, pixel values, and named anti-patterns the user mentioned in PRODUCT.md. **Every anti-reference in PRODUCT.md should show up here as a "Don't" with the same language**, so the visual spec carries the strategic line through. Quote PRODUCT.md directly where possible: if PRODUCT.md says *"avoid dark mode with purple gradients, neon accents, glassmorphism"*, the Don'ts here should repeat that by name. +Concrete, forceful guardrails. Lead each with "Do" or "Don't". Be specific: include exact colors, pixel values, and named anti-patterns the user mentioned in PRODUCT.md. **Every anti-reference in PRODUCT.md should show up here as a "Don't" with the same language**, so the visual spec carries the strategic line through. Quote PRODUCT.md directly where possible: if PRODUCT.md says *"avoid dark mode with purple gradients, neon accents, glassmorphism"*, the Don'ts here should repeat that by name. ### Do: - **Do** [specific prescription with exact values / named rule]. - **Do** [...] ### Don't: -- **Don't** [specific prohibition — e.g. "use border-left greater than 1px as a colored stripe"]. +- **Don't** [specific prohibition, e.g. "use border-left greater than 1px as a colored stripe"]. - **Don't** [...] - **Don't** [...] ``` @@ -280,7 +280,7 @@ Regenerate the sidecar whenever you regenerate DESIGN.md. If the user only asks ], "narrative": { "northStar": "The Editorial Sanctuary", - "overview": "2-3 paragraphs of the philosophy — pulled from DESIGN.md Overview section.", + "overview": "2-3 paragraphs of the philosophy, pulled from DESIGN.md Overview section.", "keyCharacteristics": ["...", "..."], "rules": [{ "name": "The One Voice Rule", "body": "...", "section": "colors|typography|elevation" }], "dos": ["Do use ..."], @@ -289,14 +289,14 @@ Regenerate the sidecar whenever you regenerate DESIGN.md. If the user only asks } ``` -**What changed from schemaVersion 1.** The old sidecar carried token primitive arrays (`tokens.colors[]`, `tokens.typography[]`, etc.). Those values now live in the frontmatter. The sidecar only carries metadata that can't live in the frontmatter — tonal ramps, canonical OKLCH when the hex is an approximation, display names, role hints — keyed by the frontmatter token name (`colorMeta.`, `typographyMeta.`). Components still carry full HTML/CSS because Stitch's 8-prop set can't hold them. +**What changed from schemaVersion 1.** The old sidecar carried token primitive arrays (`tokens.colors[]`, `tokens.typography[]`, etc.). Those values now live in the frontmatter. The sidecar only carries metadata that can't live in the frontmatter (tonal ramps, canonical OKLCH when the hex is an approximation, display names, role hints), keyed by the frontmatter token name (`colorMeta.`, `typographyMeta.`). Components still carry full HTML/CSS because Stitch's 8-prop set can't hold them. #### Component translation rules -The `html` and `css` fields must be **self-contained, drop-in snippets** that render correctly when injected into a shadow DOM. The panel applies them directly — no post-processing, no framework runtime. +The `html` and `css` fields must be **self-contained, drop-in snippets** that render correctly when injected into a shadow DOM. The panel applies them directly: no post-processing, no framework runtime. 1. **Tailwind expansion.** If the source uses Tailwind (className="bg-primary text-white rounded-lg px-6 py-3"), expand every utility to literal CSS properties in the `css` string. Do **not** reference Tailwind classes; do **not** assume a Tailwind CSS bundle is loaded. Each component is self-contained. -2. **Token resolution.** If the project exposes tokens as CSS custom properties on `:root` (e.g. `--color-primary`, `--radius-md`), reference them via `var(--color-primary)` — they inherit through the shadow DOM and stay live-bound. If tokens live only in JS theme objects (styled-components, CSS-in-JS), resolve to literal values at generation time. +2. **Token resolution.** If the project exposes tokens as CSS custom properties on `:root` (e.g. `--color-primary`, `--radius-md`), reference them via `var(--color-primary)`; they inherit through the shadow DOM and stay live-bound. If tokens live only in JS theme objects (styled-components, CSS-in-JS), resolve to literal values at generation time. 3. **Icons.** Inline as SVG. Do not reference Lucide/Heroicons packages, icon fonts, or ``. A typical icon is 16-24px; copy the SVG path data directly. 4. **States.** Include `:hover`, `:focus-visible`, and (if meaningful) `:active` rules inline. A static default-only snapshot makes the panel feel dead. Hover + focus rules in the CSS make it feel alive. 5. **Reset bloat.** Extract only the component's *distinctive* CSS (background, color, padding, border-radius, typography, transition). Skip universal resets (`box-sizing: border-box`, `line-height: inherit`, `-webkit-font-smoothing`). The panel already has a neutral canvas; don't re-ship resets. @@ -308,13 +308,13 @@ Aim for a tight set of **5-10 components** that best represent the visual system - **Canonical primitives (always include if the project has them):** button (each variant as a separate component entry), input/text field, navigation, chip/tag, card. - **Signature components (include if distinctive):** hero CTA, featured card, filter pill, any custom pattern the user mentioned as important in PRODUCT.md. -- **Skip the rest.** Utility components, form building blocks, wrapper layouts — not worth documenting unless visually distinctive. +- **Skip the rest.** Utility components, form building blocks, wrapper layouts: not worth documenting unless visually distinctive. If the project has **no component library yet** (bare landing page, new project), synthesize canonical primitives from the tokens using best-practice defaults consistent with the DESIGN.md's rules. Every DESIGN.json has *something* to render, even on day zero. #### Tonal ramps -For each color token, generate an 8-step `tonalRamp` array — dark to light, same hue and chroma, stepped lightness from ~15% to ~95%. The panel renders this as a strip under the swatch. If the project already defines a tonal scale (Material `surface-container-low` family, Tailwind-style `blue-50..blue-900`), use those values. Otherwise synthesize in OKLCH. +For each color token, generate an 8-step `tonalRamp` array: dark to light, same hue and chroma, stepped lightness from ~15% to ~95%. The panel renders this as a strip under the swatch. If the project already defines a tonal scale (Material `surface-container-low` family, Tailwind-style `blue-50..blue-900`), use those values. Otherwise synthesize in OKLCH. #### Narrative mapping @@ -331,7 +331,7 @@ Do not reword. The panel shows these as secondary collapsible context; the same ### Step 5: Confirm, refine, and refresh session cache 1. Show the user the full DESIGN.md you wrote. Briefly highlight the non-obvious creative choices (descriptive color names, atmosphere language, named rules). -2. Mention that `DESIGN.json` was also written alongside — the live panel will now render this project's actual button/input/nav primitives instead of generic approximations. +2. Mention that `DESIGN.json` was also written alongside; the live panel will now render this project's actual button/input/nav primitives instead of generic approximations. 3. Offer to refine any section: "Want me to revise a section, add component patterns I missed, or adjust the atmosphere language?" 4. **Refresh the session cache.** Run `node .agents/skills/impeccable/scripts/load-context.mjs` one final time so the newly-written DESIGN.md lands in conversation. Subsequent commands in this session will use the fresh version automatically without re-reading. @@ -350,24 +350,24 @@ If the user prefers to skip, stop. No file. Group into one `AskUserQuestion` interaction. Options must be concrete. 1. **Color strategy.** Pick one: - - Restrained — tinted neutrals + one accent ≤10% - - Committed — one saturated color carries 30–60% of the surface - - Full palette — 3–4 named color roles, each deliberate - - Drenched — the surface IS the color + - Restrained: tinted neutrals + one accent ≤10% + - Committed: one saturated color carries 30–60% of the surface + - Full palette: 3–4 named color roles, each deliberate + - Drenched: the surface IS the color Then: one hue family or anchor reference ("deep teal", "mustard", "Klim #ff4500 orange"). 2. **Typography direction.** Pick one (specific fonts come later): - Serif display + sans body - - Single sans (warm / technical / geometric / humanist — pick a feel) + - Single sans (warm / technical / geometric / humanist; pick a feel) - Display + mono - Mono-forward - Editorial script + sans 3. **Motion energy.** Pick one: - - Restrained — state changes only - - Responsive — feedback + transitions, no choreography - - Choreographed — orchestrated entrances, scroll-driven sequences + - Restrained: state changes only + - Responsive: feedback + transitions, no choreography + - Choreographed: orchestrated entrances, scroll-driven sequences 4. **Three named references.** Brands, products, printed objects. Not adjectives. @@ -380,19 +380,19 @@ Use the six-section spec from Scan mode. Populate what the interview answers; le Lead the file with: ```markdown - + ``` Per-section guidance in seed mode: - **Overview**: Creative North Star and philosophy phrased from the answers (color strategy + motion energy + references). Reference the user's anti-reference directly. -- **Colors**: Color strategy as a Named Rule (e.g. *"The Drenched Rule. The surface IS the color."*). Hue family or anchor reference. No hex values — mark as `[to be resolved during implementation]`. -- **Typography**: the direction the user picked (e.g. "Serif display + sans body"). No font names yet — `[font pairing to be chosen at implementation]`. +- **Colors**: Color strategy as a Named Rule (e.g. *"The Drenched Rule. The surface IS the color."*). Hue family or anchor reference. No hex values; mark as `[to be resolved during implementation]`. +- **Typography**: the direction the user picked (e.g. "Serif display + sans body"). No font names yet: `[font pairing to be chosen at implementation]`. - **Elevation**: inferred from motion energy. Restrained/Responsive → flat by default; Choreographed → layered. One sentence. -- **Components**: omit entirely — no components exist yet. +- **Components**: omit entirely; no components exist yet. - **Do's and Don'ts**: carry PRODUCT.md's anti-references directly plus the anti-reference named in Q5. -Seed mode writes a minimal frontmatter with `name` and `description` only — no colors, typography, rounded, spacing, or components yet. Real tokens land on the next Scan-mode run. Skip the `DESIGN.json` sidecar in seed mode for the same reason: nothing to render. +Seed mode writes a minimal frontmatter with `name` and `description` only; no colors, typography, rounded, spacing, or components yet. Real tokens land on the next Scan-mode run. Skip the `DESIGN.json` sidecar in seed mode for the same reason: nothing to render. ### Step 4: Confirm and refresh session cache @@ -402,14 +402,14 @@ Seed mode writes a minimal frontmatter with `name` and `description` only — no ## Style guidelines -- **Frontmatter first, prose second.** Tokens go in the YAML frontmatter; prose contextualizes them. Don't redefine a token value in two places — the frontmatter is normative. +- **Frontmatter first, prose second.** Tokens go in the YAML frontmatter; prose contextualizes them. Don't redefine a token value in two places; the frontmatter is normative. - **Cite PRODUCT.md anti-references by name** in the Do's and Don'ts section. If PRODUCT.md lists "SaaS landing-page clichés" or "generic AI tool marketing" as anti-references, the DESIGN.md Don'ts should repeat those phrases verbatim so the visual spec enforces the strategic line. - **Match the spec, don't invent new sections.** The six section names are fixed. If you have Layout/Motion/Responsive content to document, fold it into Overview (philosophy-level rules) or Components (per-component behavior). - **Descriptive > technical**: "Gently curved edges (8px radius)" > "rounded-lg". Include the technical value in parens, lead with the description. - **Functional > decorative**: for each token, explain WHERE and WHY it's used, not just WHAT it is. -- **Exact values in parens**: hex codes, px/rem values, font weights — always the number in parens alongside the description. +- **Exact values in parens**: hex codes, px/rem values, font weights; always the number in parens alongside the description. - **Use Named Rules**: `**The [Name] Rule.** [short doctrine]`. These are memorable, citable, and much stickier for AI consumers than bullet lists. Stitch's own outputs use them heavily ("The No-Line Rule", "The Ghost Border Fallback"). Aim for 1-3 per section. -- **Be forceful**. The voice of a design director. "Prohibited", "forbidden", "never", "always" — not "consider", "might", "prefer". Match PRODUCT.md's tone. +- **Be forceful**. The voice of a design director. "Prohibited", "forbidden", "never", "always", not "consider", "might", "prefer". Match PRODUCT.md's tone. - **Concrete anti-pattern tests**. Stitch writes things like *"If it looks like a 2014 app, the shadow is too dark and the blur is too small."* A one-sentence audit test beats a paragraph of principle. - **Reference PRODUCT.md**. The anti-references section of PRODUCT.md should directly inform the Do's and Don'ts section here. Quote or paraphrase. - **Group colors by role**, not by hex-order or hue-order. Primary / Secondary / Tertiary / Neutral is the spec ordering. @@ -417,7 +417,7 @@ Seed mode writes a minimal frontmatter with `name` and `description` only — no ## Pitfalls - Don't paste raw CSS class names. Translate to descriptive language. -- Don't extract every token. Stop at what's actually reused — one-offs pollute the system. +- Don't extract every token. Stop at what's actually reused; one-offs pollute the system. - Don't invent components that don't exist. If the project only has buttons and cards, only document those. - Don't overwrite an existing DESIGN.md without asking. - Don't duplicate content from PRODUCT.md. DESIGN.md is strictly visual. diff --git a/.agents/skills/impeccable/reference/extract.md b/.agents/skills/impeccable/reference/extract.md index 5c573e00..f8d863ce 100644 --- a/.agents/skills/impeccable/reference/extract.md +++ b/.agents/skills/impeccable/reference/extract.md @@ -67,4 +67,3 @@ Update design system documentation: - Create tokens for every single value (tokens should have semantic meaning) - Extract things that differ in intent (two buttons that look similar but serve different purposes should stay separate) -Remember: A good design system is a living system. Extract patterns as they emerge, enrich them thoughtfully, and maintain them consistently. diff --git a/.agents/skills/impeccable/reference/harden.md b/.agents/skills/impeccable/reference/harden.md index a27c669a..917be521 100644 --- a/.agents/skills/impeccable/reference/harden.md +++ b/.agents/skills/impeccable/reference/harden.md @@ -1,4 +1,4 @@ -Strengthen interfaces against edge cases, errors, internationalization issues, and real-world usage scenarios that break idealized designs. +Designs that only work with perfect data aren't production-ready. Harden the interface against the inputs, errors, languages, and network conditions that real users will throw at it. ## Assess Hardening Needs @@ -344,4 +344,4 @@ Test thoroughly with edge cases: - **Errors**: Force API errors, test all error states - **Empty**: Remove all data, test empty states -Remember: You're hardening for production reality, not demo perfection. Expect users to input weird data, lose connection mid-flow, and use your product in unexpected ways. Build resilience into every component. +When edge cases are covered, hand off to `$impeccable polish` for the final pass. diff --git a/.agents/skills/impeccable/reference/heuristics-scoring.md b/.agents/skills/impeccable/reference/heuristics-scoring.md index fd5b1b08..edbe5028 100644 --- a/.agents/skills/impeccable/reference/heuristics-scoring.md +++ b/.agents/skills/impeccable/reference/heuristics-scoring.md @@ -1,6 +1,6 @@ # Heuristics Scoring Guide -Score each of Nielsen's 10 Usability Heuristics on a 0–4 scale. Be honest — a 4 means genuinely excellent, not "good enough." +Score each of Nielsen's 10 Usability Heuristics on a 0–4 scale. Be honest: a 4 means genuinely excellent, not "good enough." ## Nielsen's 10 Heuristics @@ -18,11 +18,11 @@ Keep users informed about what's happening through timely, appropriate feedback. **Scoring**: | Score | Criteria | |-------|----------| -| 0 | No feedback — user is guessing what happened | -| 1 | Rare feedback — most actions produce no visible response | -| 2 | Partial — some states communicated, major gaps remain | -| 3 | Good — most operations give clear feedback, minor gaps | -| 4 | Excellent — every action confirms, progress is always visible | +| 0 | No feedback; user is guessing what happened | +| 1 | Rare feedback; most actions produce no visible response | +| 2 | Partial; some states communicated, major gaps remain | +| 3 | Good; most operations give clear feedback, minor gaps | +| 4 | Excellent; every action confirms, progress is always visible | ### 2. Match Between System and Real World @@ -39,9 +39,9 @@ Speak the user's language. Follow real-world conventions. Information appears in | Score | Criteria | |-------|----------| | 0 | Pure tech jargon, alien to users | -| 1 | Mostly confusing — requires domain expertise to navigate | -| 2 | Mixed — some plain language, some jargon leaks through | -| 3 | Mostly natural — occasional term needs context | +| 1 | Mostly confusing; requires domain expertise to navigate | +| 2 | Mixed; some plain language, some jargon leaks through | +| 3 | Mostly natural; occasional term needs context | | 4 | Speaks the user's language fluently throughout | ### 3. User Control and Freedom @@ -58,11 +58,11 @@ Users need a clear "emergency exit" from unwanted states without extended dialog **Scoring**: | Score | Criteria | |-------|----------| -| 0 | Users get trapped — no way out without refreshing | -| 1 | Difficult exits — must find obscure paths to escape | -| 2 | Some exits — main flows have escape, edge cases don't | -| 3 | Good control — users can exit and undo most actions | -| 4 | Full control — undo, cancel, back, and escape everywhere | +| 0 | Users get trapped; no way out without refreshing | +| 1 | Difficult exits; must find obscure paths to escape | +| 2 | Some exits; main flows have escape, edge cases don't | +| 3 | Good control; users can exit and undo most actions | +| 4 | Full control; undo, cancel, back, and escape everywhere | ### 4. Consistency and Standards @@ -78,11 +78,11 @@ Users shouldn't wonder whether different words, situations, or actions mean the **Scoring**: | Score | Criteria | |-------|----------| -| 0 | Inconsistent everywhere — feels like different products stitched together | -| 1 | Many inconsistencies — similar things look/behave differently | -| 2 | Partially consistent — main flows match, details diverge | -| 3 | Mostly consistent — occasional deviation, nothing confusing | -| 4 | Fully consistent — cohesive system, predictable behavior | +| 0 | Inconsistent everywhere; feels like different products stitched together | +| 1 | Many inconsistencies; similar things look/behave differently | +| 2 | Partially consistent; main flows match, details diverge | +| 3 | Mostly consistent; occasional deviation, nothing confusing | +| 4 | Fully consistent; cohesive system, predictable behavior | ### 5. Error Prevention @@ -98,11 +98,11 @@ Better than good error messages is a design that prevents problems in the first **Scoring**: | Score | Criteria | |-------|----------| -| 0 | Errors easy to make — no guardrails anywhere | -| 1 | Few safeguards — some inputs validated, most aren't | -| 2 | Partial prevention — common errors caught, edge cases slip | -| 3 | Good prevention — most error paths blocked proactively | -| 4 | Excellent — errors nearly impossible through smart constraints | +| 0 | Errors easy to make; no guardrails anywhere | +| 1 | Few safeguards; some inputs validated, most aren't | +| 2 | Partial prevention; common errors caught, edge cases slip | +| 3 | Good prevention; most error paths blocked proactively | +| 4 | Excellent; errors nearly impossible through smart constraints | ### 6. Recognition Rather Than Recall @@ -118,15 +118,15 @@ Minimize memory load. Make objects, actions, and options visible or easily retri **Scoring**: | Score | Criteria | |-------|----------| -| 0 | Heavy memorization — users must remember paths and commands | -| 1 | Mostly recall — many hidden features, few visible cues | -| 2 | Some aids — main actions visible, secondary features hidden | -| 3 | Good recognition — most things discoverable, few memory demands | -| 4 | Everything discoverable — users never need to memorize | +| 0 | Heavy memorization; users must remember paths and commands | +| 1 | Mostly recall; many hidden features, few visible cues | +| 2 | Some aids; main actions visible, secondary features hidden | +| 3 | Good recognition; most things discoverable, few memory demands | +| 4 | Everything discoverable; users never need to memorize | ### 7. Flexibility and Efficiency of Use -Accelerators — invisible to novices — speed up expert interaction. +Accelerators, invisible to novices, speed up expert interaction. **Check for**: - Keyboard shortcuts for common actions @@ -138,11 +138,11 @@ Accelerators — invisible to novices — speed up expert interaction. **Scoring**: | Score | Criteria | |-------|----------| -| 0 | One rigid path — no shortcuts or alternatives | -| 1 | Limited flexibility — few alternatives to the main path | -| 2 | Some shortcuts — basic keyboard support, limited bulk actions | -| 3 | Good accelerators — keyboard nav, some customization | -| 4 | Highly flexible — multiple paths, power features, customizable | +| 0 | One rigid path; no shortcuts or alternatives | +| 1 | Limited flexibility; few alternatives to the main path | +| 2 | Some shortcuts; basic keyboard support, limited bulk actions | +| 3 | Good accelerators; keyboard nav, some customization | +| 4 | Highly flexible; multiple paths, power features, customizable | ### 8. Aesthetic and Minimalist Design @@ -158,11 +158,11 @@ Interfaces should not contain irrelevant or rarely needed information. Every ele **Scoring**: | Score | Criteria | |-------|----------| -| 0 | Overwhelming — everything competes for attention equally | -| 1 | Cluttered — too much noise, hard to find what matters | -| 2 | Some clutter — main content clear, periphery noisy | -| 3 | Mostly clean — focused design, minor visual noise | -| 4 | Perfectly minimal — every element earns its pixel | +| 0 | Overwhelming; everything competes for attention equally | +| 1 | Cluttered; too much noise, hard to find what matters | +| 2 | Some clutter; main content clear, periphery noisy | +| 3 | Mostly clean; focused design, minor visual noise | +| 4 | Perfectly minimal; every element earns its pixel | ### 9. Help Users Recognize, Diagnose, and Recover from Errors @@ -178,11 +178,11 @@ Error messages should use plain language, precisely indicate the problem, and co **Scoring**: | Score | Criteria | |-------|----------| -| 0 | Cryptic errors — codes, jargon, or no message at all | -| 1 | Vague errors — "Something went wrong" with no guidance | -| 2 | Clear but unhelpful — names the problem but not the fix | -| 3 | Clear with suggestions — identifies problem and offers next steps | -| 4 | Perfect recovery — pinpoints issue, suggests fix, preserves user work | +| 0 | Cryptic errors; codes, jargon, or no message at all | +| 1 | Vague errors; "Something went wrong" with no guidance | +| 2 | Clear but unhelpful; names the problem but not the fix | +| 3 | Clear with suggestions; identifies problem and offers next steps | +| 4 | Perfect recovery; pinpoints issue, suggests fix, preserves user work | ### 10. Help and Documentation @@ -200,9 +200,9 @@ Even if the system is usable without docs, help should be easy to find, task-foc |-------|----------| | 0 | No help available anywhere | | 1 | Help exists but hard to find or irrelevant | -| 2 | Basic help — FAQ or docs exist, not contextual | -| 3 | Good documentation — searchable, mostly task-focused | -| 4 | Excellent contextual help — right info at the right moment | +| 2 | Basic help; FAQ or docs exist, not contextual | +| 3 | Good documentation; searchable, mostly task-focused | +| 4 | Excellent contextual help; right info at the right moment | --- @@ -212,11 +212,11 @@ Even if the system is usable without docs, help should be easy to find, task-foc | Score Range | Rating | What It Means | |-------------|--------|---------------| -| 36–40 | Excellent | Minor polish only — ship it | +| 36–40 | Excellent | Minor polish only; ship it | | 28–35 | Good | Address weak areas, solid foundation | | 20–27 | Acceptable | Significant improvements needed before users are happy | -| 12–19 | Poor | Major UX overhaul required — core experience broken | -| 0–11 | Critical | Redesign needed — unusable in current state | +| 12–19 | Poor | Major UX overhaul required; core experience broken | +| 0–11 | Critical | Redesign needed; unusable in current state | --- @@ -226,7 +226,7 @@ Tag each individual issue found during scoring with a priority level: | Priority | Name | Description | Action | |----------|------|-------------|--------| -| **P0** | Blocking | Prevents task completion entirely | Fix immediately — this is a showstopper | +| **P0** | Blocking | Prevents task completion entirely | Fix immediately; this is a showstopper | | **P1** | Major | Causes significant difficulty or confusion | Fix before release | | **P2** | Minor | Annoyance, but workaround exists | Fix in next pass | | **P3** | Polish | Nice-to-fix, no real user impact | Fix if time permits | diff --git a/.agents/skills/impeccable/reference/interaction-design.md b/.agents/skills/impeccable/reference/interaction-design.md index 19d6809a..15aed5b2 100644 --- a/.agents/skills/impeccable/reference/interaction-design.md +++ b/.agents/skills/impeccable/reference/interaction-design.md @@ -42,11 +42,11 @@ button:focus-visible { ## Form Design: The Non-Obvious -**Placeholders aren't labels**—they disappear on input. Always use visible `