Agent Skills: Impeccable — the design hub

Impeccable — the design hub

This is the ONE home for durable design knowledge. Every design verb (/impeccable --craft, --typeset, --colorize, --layout, --bolder, --harden, …) loads this hub, so the aesthetic is present structurally — you never need it re-stated.

This hub POINTS; it does not inline. The banned rules, voice anchors, preferences, and detector rules each have a single canonical home under docs/concepts/design-contract/. Re-inlining them here would recreate the lossy monolith this system was built to delete (#POISON_PATH). Read the source files when you reach for the corresponding move — they carry the full voice, regex signals, and substitutes.

Path note: in this repo the collection lives at docs/concepts/...; deployed it lives at ~/.claude/docs/concepts/.... Both resolve to the same content. Read whichever exists.

1. The felt-state baseline (the spine)

Start every interface from the felt state of the person, not the task. This is the interfaces-that-feel practice — it is the first thing you load.

→ skills/interfaces-that-feel/SKILL.md (the full practice: felt-state framing, motion craft, copy voice, empty states, error messages, loading, onboarding, micro-interactions).

Technical correctness is the floor. The ceiling is: does this product know the user is a person?

2. The aesthetic — voice anchors (the user's own words)

The voice anchors are load-bearing direct quotes from Adil. They are the why behind every refusal and move below. Do not paraphrase or dilute them; edits that weaken them must be refused (#POISON_PATH).

→ docs/concepts/design-contract/voice-anchors.md — the full anchor set (17 anchors).

→ docs/concepts/design-contract/persona.md — the POSITIVE side of the aesthetic (taste, references, gravity). The anchors and banned rules say what is refused; the persona says what is aimed at — the flatness mission, context-over-reflex, the named references, the composition discipline (entry point / pace / density-per-moment). Read it before composing any new surface — FORWARD seeds draw from it at bind time. Judgment + gravity, never a house style; anti-convergence outranks it. (Pointer — the content lives in the file, not here.)

A few that orient the whole system (read the file for all of them):

• "The use of Geist = vercel → no thought in typography. Boring, plain, looks like every other SaaS."
• "Whatever color that background is hurts my eyes; the gradients only make it worse." (AI-purple)
• "I do not fuck around with alignment. Pixel perfect precision, otherwise I can't help but notice."
• "A great one carries what the product is in a way that's immersive, without announcing. There is nothing uglier than annotated art."
• "Smooth, elegant motion — not perspective, just directional."

Core principles (Adil's, beside Bakaus's direction)

• Composure — self-possession + carrying-without-announcing
• Exact structure, honest surface — pixel-precise geometry with real texture
• Balance as organizing principle — negative/positive space discipline; the entry point carries the viewer to the destination without announcing
• Shown, not announced — the Nike/Porsche mode. Annotated art is ugly.
• Scale as registration — don't miniaturize what matters; don't inflate what doesn't
• Life beside weight — multiple registers cohabit the same frame
• Dignity preservation — subjects respected, not displayed

Commit to a BOLD aesthetic direction. Bold maximalism and refined minimalism both work — the key is intentionality, not intensity. Make unexpected choices true to the context. No design should be the same across projects. NEVER converge on common choices across generations.

3. The refusals (banned) — what is NEVER acceptable

Each banned rule is a named refusal with full voice + regex signals + substitutes. Consult the rule when you reach for the move it forbids. Most map to a detector rule id (§5) that BLOCKS at the gate.

| Refusal | Source rule | Detector rule(s) | |---|---|---| | Tailwind palette (utility classes + hex values) | design-contract/banned/colors.md | tailwind-palette-utilities, tailwind-hex-values, ai-color-palette | | Geist + extended reflex font list | design-contract/banned/fonts.md | reflex-fonts, geist-imports, overused-font, single-font | | AI-purple/magenta/pink gradients | design-contract/banned/gradients.md | purple-pink-gradients, gradient-text | | iOS-as-default / pretend-variation | design-contract/banned/generic-ui-defaults.md | (taste — advisory) | | Motion suddenness / default ease | design-contract/banned/motion-suddenness.md | default-ease-transition, bouncy-easing, bounce-easing | | Chamfer stack (inset highlight + shadow + gradient) | design-contract/banned/chamfered-buttons.md | inset-highlight-shadow | | Alignment violations / floating elements | design-contract/banned/alignment-spacing.md | (taste — advisory) | | AI-signature rounded corners | design-contract/banned/rounded-corners.md | border-accent-on-rounded | | Photorealistic skeuomorphism as default | design-contract/banned/skeuomorphism.md | (taste — advisory) | | Side-stripe borders on cards/callouts | design-contract/banned/alignment-spacing.md | side-stripe-borders, side-tab | | Monospace-as-"technical" shorthand | design-contract/banned/typography-mono.md | (taste — advisory) | | Uniform tile / same-card-grid layout | design-contract/banned/uniform-tile-layout.md | icon-tile-stack, nested-cards | | Utility sprawl / scattered design authority | design-contract/banned/css-architecture.md | utility-sprawl (advisory only, never blocks) |

Absolute bans (rewrite the element entirely if you catch yourself reaching for these):

• Side-stripe borders (border-left/right > 1px, including via CSS vars) on cards/list-items/ callouts/alerts — the most overused dashboard "touch". Reach for full borders, background tints, leading numbers/icons, or nothing.
• Gradient text (background-clip: text + any gradient) — top-three AI tell. Use solid color; for emphasis use weight or size.

4. The positive moves (preferences) — what to reach for instead

Each preference is a positive catalog/procedure. Consult when making the corresponding decision.

| Move | Source preference | |---|---| | Typography fonts (22 fonts, 4 categories) | design-contract/preferences/typography-fonts.md | | Type scale & hierarchy (non-uniform) | design-contract/preferences/typography-scale.md | | Typography spacing (junction discipline — no double-stacked margins) | design-contract/preferences/typography-spacing.md | | Alignment precision (7 optical rules) | design-contract/preferences/alignment-precision.md | | Motion references (directional, not perspective) | design-contract/preferences/motion-references.md | | Monospace, used well | design-contract/preferences/typography-mono.md | | CSS architecture (centralized role taxonomy, taxonomy-first, @layer, tokens as boundary) | design-contract/preferences/css-architecture.md |

Always-on craft (do these without consulting a reference)

• Type: modular scale, fluid clamp() on marketing/content headings, fixed rem for app/dashboard UI. Fewer sizes, more contrast (≥1.25 ratio). Cap body at ~65–75ch. Line-height scales inversely with line length; add 0.05–0.1 for light-on-dark.
• Color: OKLCH, not HSL. Reduce chroma toward white/black. Tint neutrals toward the brand hue (chroma 0.005–0.01). 60-30-10 by visual weight. No pure #000/#fff. Theme (light/dark) is DERIVED from audience + viewing context, never a safe default.
• Space: 4pt scale with semantic token names. gap over margins. Vary spacing for hierarchy; break the grid intentionally. repeat(auto-fit, minmax(280px, 1fr)) is the breakpoint-free card grid. Container queries for components, viewport queries for page layout.
• Motion: high-impact moments over scattered micro-interactions. Exponential easing (ease-out-quart/quint/expo). Transform + opacity only — never animate layout. No bounce/elastic.

Font selection procedure (do this BEFORE typing any font name)

The failure mode is: "told not to use Inter, so I reach for my next favorite → new monoculture."

1. Write 3 concrete brand-voice words (NOT "modern"/"elegant" — dead categories).
2. List the 3 fonts you'd reflexively reach for. If any are in the reflex list (design-contract/banned/fonts.md — Fraunces, Newsreader, Playfair, IBM Plex, Space Grotesk, Inter, DM Sans, Outfit, Plus Jakarta, Instrument, et al), reject them.
3. Browse a catalog with the 3 words in mind (Google Fonts, Pangram Pangram, Future Fonts, Klim, Velvetyne …). Find a font that fits the brand as a physical object. Reject the first "designy" pick.
4. Cross-check: "elegant" is not necessarily a serif; "technical" not necessarily a sans; "warm" not Fraunces. If the pick lines up with reflex, go back to step 3.

CSS architecture (doctrine B — centralize authority, NOT a Tailwind ban)

Design authority lives in a named role/token vocabulary; agents COMPOSE from it, they do not invent design inline. Greenfield default: semantic CSS + cascade + @layer, taxonomy designed first. Brownfield: respect the detected approach, enforce centralization within it. No raw palette utilities (P0). Token-mapped semantic Tailwind is fine; utility SPRAWL is advisory only. Refusal: banned/css-architecture.md. Procedure: preferences/css-architecture.md. This hub states the PRINCIPLE; enforcement lives in the detector floor + the validator agent.

5. The detector — the named-slop floor

The detector is a deterministic CLI that names slop. It is the FLOOR of the gate, never the taste ceiling. Run it in-repo as:

node /Users/adilkalam/ORCA-OS/mcp/design-detector/bin/designcheck.js detect --json <path> 2>&1; echo "EXIT=$?"

Use the LOCAL node entry above — npx designcheck is NOT a published package.

Contract (verified): EXIT 0 + [] = clean. EXIT 2 = findings, and the findings JSON arrives on STDERR (stdout is empty), so capture 2>&1 and key the decision off the exit code. Each finding is {antipattern:<ruleId>, name, description, file, line, snippet}.

Rule severities read from docs/concepts/design-contract/detector-rules.json:

• BLOCKING (a finding forces BLOCK): ai-color-palette, border-accent-on-rounded, bounce-easing, bouncy-easing, dark-glow, default-ease-transition, everything-centered, flat-type-hierarchy, geist-imports, gradient-text, icon-tile-stack, inset-highlight-shadow, monotonous-spacing, nested-cards, overused-font, purple-pink-gradients, reflex-fonts, side-stripe-borders, side-tab, single-font, tailwind-hex-values, tailwind-palette-utilities.
• ADVISORY (logged, never blocks): all-caps-body, cramped-padding, gray-on-color, justified-text, layout-transition, line-length, low-contrast, pure-black-white, skipped-heading, tight-leading, tiny-text, utility-sprawl, wide-tracking.

Owner-cares-about (per-project severity, override-config-driven). reflex-fonts and geist-imports are the web analogs of what the owner instructs on repeatedly — the Geist/Inter reflex he calls out by name ("no thought in typography, looks like every other SaaS"). Their enforcement severity is set per project, not by a frozen global map: a project may pin them to BLOCK (owner-instructed) and the lane reads that from the project detector config / BOUND_CONSTRAINTS[].severity, exactly as the iOS lane treats system-font-reflex/ios-default-reflex. Severity tracks what the owner cares about, and a live owner instruction can suppress even these via an OVERRIDE (§6) for a named scope — owner outranks the floor.

6. How the rules actually bind (floor vs ceiling — honest)

Precedence (read this first): the owner outranks this hub. Everything below is a default for when the owner has not spoken to the point — never a ceiling over his live word. The order is fixed: (1) the owner's explicit, in-context instruction; (2) the aesthetic (banned rules / preferences); (3) the deterministic detector. A banned rule is derived from the owner; it cannot outrank him. When his live instruction contradicts a standing banned rule or detector rule (e.g. "this brief is over-restrictive — use the purple gradient here", or "the Geist face is right for this surface"), that instruction wins — bound as an OVERRIDE constraint (docs/reference/design-lane.md §Precedence) that the validator subtracts before the verdict and that is written back to {project}/.design-overrides.json so the suppressed rule stops firing for that scope on future runs. The override is owner-authored, so it is ratified by construction (unlike a banned rule the system distilled and froze without his sign-off). An override honored once but not written back re-loses on the next task — that recurrence is the precise failure this precedence kills. See design-lane.md §Precedence for the full mechanism.

The hub being present is necessary but not sufficient. Two mechanisms do the binding:

1. The lane (docs/reference/design-lane.md) — a thin orchestrator binds typed FORBIDDEN/FORWARD constraints via a cognition checkpoint, spawns a SEPARATE builder, then a SEPARATE fresh-context validator that judges against the bound ids + the detector. The model never grades its own output.
2. Structured selection — felt-state binds through /shape (3-round discovery for new work) and three-variants-pick-one (/live) for iteration. Inline reasoning narration is NOT the mechanism.

The honest ceiling (state it, never hide it):

• Guaranteed: rules present (structural); adjudication external (separate validator + detector floor); no named slop; no silent no-op.
• NOT guaranteed: good taste — irreducibly the validator's judgment + the user's eye is the taste ceiling. The lane raises the floor and externalizes judgment; it does not manufacture taste. The detector/validator are hard-on-named-slop, advisory-on-taste. Anyone claiming more is selling another constraint-bind (#POISON_PATH).

7. Project context (read before any design work)

Design output is generic without project context. Two per-project files carry it:

| Layer | Where | What | |---|---|---| | Strategic | {project}/.claude/PRODUCT.md | Register, users, anti-references AS NAMED BRANDS, design principles, accessibility. No colors/fonts/pixels. | | Visual | {project}/.claude/DESIGN.md | Stitch-spec contract: colors (hex sRGB), typography hierarchy, components (8-prop max), Do's-and-Don'ts, Role Taxonomy. |

If PRODUCT.md is missing → route to /impeccable --teach (writes it). If DESIGN.md is missing → route to /impeccable --document. You CANNOT infer strategic context from the codebase; only the creator provides it. Visual context CAN be partially extracted from code (--document scan mode).

8. Reference index (deeper material — read on demand)

The impeccable-reference/ files carry the deep, consult-on-demand material:

• docs/concepts/impeccable-reference/typography.md — OpenType features, web font loading, scales
• docs/concepts/impeccable-reference/color-and-contrast.md — contrast, accessibility, palette construction
• docs/concepts/impeccable-reference/spatial-design.md — grids, container queries, optical adjustments
• docs/concepts/impeccable-reference/motion-design.md — timing, easing, reduced motion
• docs/concepts/impeccable-reference/interaction-design.md — forms, focus, loading
• docs/concepts/impeccable-reference/responsive-design.md — mobile-first, fluid, container queries
• docs/concepts/impeccable-reference/ux-writing.md — labels, errors, empty states
• docs/concepts/impeccable-reference/craft.md — the --craft shape→comp→build flow
• docs/concepts/impeccable-reference/extract.md — the --extract token/component flow
• docs/concepts/impeccable-reference/extract-aesthetic.md — the --extract aesthetic sweep flow

The AI slop test

If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. A distinctive interface makes someone ask "how was this made?" not "which AI made this?" The refusals in §3 are the fingerprints of 2024–2025 AI work.