Repaint

repaint

A self-contained pipeline for frontend UI that looks designed, not generated — and behaves like it, too. It depends on no other skills and no agents — everything it needs ships in this folder. It stands on six pillars:

1. Scraping — research real, current references for the brief (your web search), not vibes.
2. Tokens — commit a concrete token system (OKLCH color + distinctive type) before any markup.
3. References — a curated library ([references/context-anchors.md](references/context-anchors.md)) of named anchors per context, art-direction directions, 2026 token defaults, a slop catalog, type-by-role, experience patterns, microcopy, and an accessibility & SEO checklist.
4. Experience — the interaction is designed, not just the pixels: honest feedback and perceived performance, forgiving input, recoverable actions, and a real keyboard path. Looks pass the eye; experience passes the hand. Gate 4, Gate 5, and the experience audit enforce it.
5. Reach — the work is accessible to every user (assistive tech) and findable by search. One semantic-HTML foundation — landmark regions, one H1 + a logical heading order, real labels, meaningful alt — serves screen readers and crawlers. Gate 6 and the accessibility & SEO audit enforce it (SEO is register-gated to public surfaces).
6. Real iteration feedback — build → render → screenshot → slop-audit + experience-audit + a11y/SEO audit → iterate, against live browser output, not a one-shot guess. The 23 [evals](evals/evals.json) are the regression harness.

Where this skill earns its keep

A capable model already produces competent generic structure on a well-specified brief (a pricing page gets a comparison table and a "Most Popular" badge unaided). Don't spend effort re-adding structure the model nails alone. The real leverage — eval-verified — is in six places the model gets wrong without help:

1. Killing cliché on open/creative briefs. Left alone, "make it bold/memorable" collapses to the same neon-gradient-on-dark or purple-gradient tells. The register lock + slop audit prevent that. This is the single biggest win.
2. Register-appropriate restraint. A product-app settings panel should be calmer than a saas-landing hero. The model over-decorates by default; the register playbook pulls it back.
3. Distinctive typography. The model defaults to Inter/system fonts; Gate 3 forces a committed type choice.
4. Compile-clean, durable output. Generated copy and tokens must actually build and be written down (Phase 3 string rule + DESIGN.md persistence).
5. Wired, honest interaction. Generated UI looks fine but the interaction is hollow — handlers that do nothing, states styled but never reached, silent submits with no loading feedback, `` with no keyboard path, generic "Something went wrong" copy. This is the experiential "AI made that". Gate 4 + Gate 5 + the experience audit force real, reachable, honest interaction.
6. Accessible & findable. Generated markup is inaccessible-by-default (` soup, no landmarks, unlabeled inputs, missing/empty alt, no /heading order) and SEO-blind (no `/meta/structured data; content trapped behind client-only JS). Gate 6 + the a11y/SEO audit enforce the one semantic foundation that serves screen readers and crawlers alike.

Mode detection (before any phase)

Art-direction mode when the brief contains: bold, editorial, experimental, scroll-driven, unforgettable, striking, art-directed, motion-heavy, avant-garde, or when the visual concept itself is the primary challenge.

Production mode (default) for everything else: dashboards, landing pages, app surfaces, settings, onboarding, data tables, command palettes, marketing sites, and any surface where credibility with a tech-savvy audience matters.

---

Phase 0 — Research references (the "scraping" pillar; skip if direction is locked)

When the design direction is open, gather real, current references before committing — do not invent a vibe:

• Use your web search for 2026 and for the named anchor's own site (e.g. "Linear pricing", "Stripe docs", "Warby Parker product page"). Pull: dominant palette, the actual typefaces, the layout pattern, and the spacing rhythm.
• Open [references/context-anchors.md](references/context-anchors.md) §A for the named anchor + concrete tokens that fit this context (retail, fintech, healthcare, editorial, mobile, b2b dashboards, auth) — it is the curated, offline version of the same research.

Extract: recommended palette, typography pairing, layout pattern, and the anti-patterns to avoid.

Skip when: the user gave a reference brand, an existing DESIGN.md is found, art-direction mode is detected, or the user gave explicit visual direction.

---

Phase 1 — Quality gates (production) / Design thinking (art-direction)

Production mode: run all 7 gates in order

Gate 0.5 — Register lock. Classify the brief into exactly one of:

• personal-portfolio — identity-first, single person
• saas-landing — product marketing, convert visitors
• product-app — post-login app surface
• marketing — blog, launch page, campaign (narrative/editorial — never a feature-card grid)
• docs — API reference, developer docs, KB

If the brief matches 2+ registers, ask one disambiguation question first. Default-DENY: SaaS-landing patterns (bento grid, dual-CTA hero, feature-row rhythm) must NOT apply to other registers without affirmative intent. In particular marketing ≠ saas-landing: a launch/announcement page gets a narrative/editorial layout + an editorial anchor (Stripe-marketing, Medium, The Verge, Linear changelog), never a feature-card grid (and NOT a .map() loop over identical feature cards: fold highlights into the narrative prose, or give each a distinct, varied treatment — alternating sides, different sizes) or product-UX anchor.

Gate 2 — Reference anchor. Pick ≥1 named industry pattern; the anchor is a contract — use actual tokens, not vibes. State it in one sentence: "Sidebar anchored to Linear; cards anchored to Stripe Dashboard." Don't reflex to Linear/Vercel — those are dev-tooling anchors, the wrong bar for an e-commerce page, a patient portal, an editorial feature, or a banking app. For ANY non-dev-tool brief, open [references/context-anchors.md](references/context-anchors.md) §A and use the named anchor for that context. Beyond a named product, anchor to the industry design system that fits the register — Carbon/Fluent/Ant for enterprise data, Polaris for commerce admin, Material 3/Apple HIG for native-feel, Primer for dev-tools ([§I](references/context-anchors.md) maps systems to contexts + the cross-cutting patterns they define). When the direction is open, name 2–3 candidate anchors as variant directions (e.g. Linear-calm · Stripe-editorial · Monzo-warm), each with a one-line trade-off, then commit to one — design-then-code: present the variants for selection before writing component code. In an autonomous or eval context — no human to pick, including when dispatched to the builder agent — default to the strongest of the 2–3, state that choice in one line, and build it in the same pass; never stop after only presenting the options. (This applies to aesthetic / anchor choice only — it does not override Gate 0.5's register disambiguation: when the brief genuinely matches 2+ registers, still surface that and ask one focused question before building.)

Gate 3 — Token spec. Lock concrete tokens before writing markup:

| Category | Must specify | |---|---| | Color | OKLCH triplets for bg, fg, muted, border, one accent — tinted toward the accent hue. Never #000/#fff. | | Type | Display family + weight, body family + weight, mono. Weight contrast ≥400 between display and body. Name the actual faces — never Inter/Roboto/Arial as the default body, not even in the fallback stack, and not a bare font-serif/font-sans generic (that resolves to Georgia/system — the "no-personality" tell). Pick a real face from [context-anchors.md](references/context-anchors.md) §E. | | Spacing | Base unit (4pt or 8pt). Max 6 steps. State where each applies. | | Radius | ≤3 values, assigned per component. | | Motion | Duration tokens (120/200/320ms). Ease curve. No bounce. | | Accessibility | WCAG 2.2: 4.5:1 (normal text), 3:1 (large/UI), focus ring ≥2px at ≥3:1, touch targets ≥44px. |

When the project has no tokens, use the 2026 token defaults in [context-anchors.md](references/context-anchors.md) §C (warm earthy neutrals + one restrained accent, 8/4px grid, semantic radius, two-part-shadow elevation).

Gate 4 — Component anatomy + interaction affordances. Every interactive component designs all 8 states: default, hover, focus, active, loading, empty, error, disabled (loading/empty/error are the most-skipped). Each state must carry three things, not just a look:

• Visual feedback — the state is perceivable (a real spinner/skeleton on load, a pressed look on active), never a silent change.
• Keyboard access — a :focus-visible ring per Gate 3 (≥2px at ≥3:1); semantic `// not . For a custom control, document its interaction model (focus order, keys, state changes) in DESIGN.md`.
• Outcome clarity — the result is announced ("Copied", Saving… → Saved, an inline error), not left for the user to guess.

Gate 5 — Experience contract. The cross-cutting interaction guarantees, beyond any single component (cross-references Gate 3 for the a11y numbers and §A for per-context density — does not restate them; [§J](references/context-anchors.md) is the psychology under these — Gestalt, Hick, Fitts, peak-end, Zeigarnik — and the dark-pattern bans):

• Honest feedback + perceived performance. Optimistic UI or a skeleton for content; a spinner only for brief actions; never a silent wait >1s. ///), real elements over ` soup; native HTML before ARIA (ARIA only to fill a gap native HTML can't).
• Exactly one `` stating the page's purpose, then a logical heading order (no level skips).
• Labels & alt — every input has a real, associated ` (never placeholder-as-label); content images carry descriptive alt, decorative images alt=""`.
• Name/role/value for any custom widget (role + aria-* state); accessible errors (aria-invalid + aria-describedby).
• Live regions — any form submit / status / async result announces via aria-live="polite" (or role="status"; alert only for time-critical), present at load with content swapped inside; never a silent handler or a bare alert().
• lang on ` (BCP-47, e.g. lang="en"); a **skip-to-main** link as the first focusable element on any page with /`.

SEO (public registers only — saas-landing, marketing, docs, e-commerce, editorial; N/A for product-app / personal-portfolio):

• A unique, descriptive ` (~50–60 chars) + a unique meta description (~120–160) + a self-referential canonical; the ` + heading hierarchy above is shared with a11y.
• Open Graph + Twitter card (absolute og:image URL, summary_large_image) for shareable pages; JSON-LD for the context (Product/Offer, Article, FAQPage, BreadcrumbList, Organization).
• Crawlable content — title/H1/body present in the server-rendered HTML (SSR/SSG), not client-JS-only; descriptive link text (never "click here"); `` set.
• Core Web Vitals targets: LCP ≤2.0s · INP ≤200ms · CLS ` tag or keyword-stuffed copy.

Gate 7 — Compile-clean contract. The output must run on the first try, not just look right (the discipline behind Claude Artifacts + v0's autofixer). Lock what is importable now so the build can't fail on a phantom dependency: in a self-contained artifact, only the sandbox-preloaded allowlist is importable; in a project-scaffold, only packages already in package.json. No import of an undeclared package, no named import the package doesn't actually export (the icon/symbol-mismatch class — the thing v0's autofixer exists to catch), no emoji-as-icon. Enforced by the pre-verify lint at the top of Phase 4. Full allowlist + forbidden-pattern list + lint checklist in [§K](references/context-anchors.md).

Art-direction mode: design thinking instead

Commit to ONE bold named direction from [context-anchors.md](references/context-anchors.md) §B — warm-editorial-serif, Swiss/neo-grotesque, soft-organic/biophilic, brutalist, typographic-maximalism, retro-futurist-3D, imperfect-by-design, deconstructed/specimen, cyber/technical, or cinematic-pacing. Each ships execution specs — exact type scale, tracking, leading, a color triplet, and a signature move — so don't stop at the name; lock its specifics. For motion-heavy directions, layer [§L motion craft](references/context-anchors.md). Choose an extreme and execute with precision. What makes it unforgettable? One distinctive thing the user will remember.

Persist the decisions to DESIGN.md (both modes)

Before writing component code, write the locked register, anchor(s), token table, chosen variant, and direction to a DESIGN.md at the project root (or update it if present). A rationale that lives only in chat is lost when the session ends, and the surface drifts. This DESIGN.md is the **approval checkpoint and the cross-surface token-lock: it is the design-then-code handoff (present the locked spec before building), and every later surface in the same project reads and reuses it — never re-derive tokens per surface, or sibling screens drift apart. If a DESIGN.md already exists, its tokens are non-negotiable — adopt them; do not invent a competing palette.**

---

Phase 2 — Scaffold

Route by project setup, and defer to any established design system — it overrides Gate 3. This is the most common way a UI pipeline regresses below a no-skill baseline: a custom OKLCH spec conflicts with a system that already owns tokens, and you get the worst of both (raw bg-red-50 colors instead of either system).

• shadcn components.json present → use its semantic tokens (bg-primary, text-muted-foreground, bg-destructive, border-input) — never raw color classes, never a parallel OKLCH palette — and its primitives (Field/Label, Button variants, cn()), and its iconLibrary.
• An established design-system library in package.json (@mui/material, antd, @shopify/polaris, @mantine/core, @carbon/react, @fluentui/react-components, @primer/react, baseui) → defer to it: its tokens/theme, components, and icon set — never a parallel OKLCH palette. [§I](references/context-anchors.md) maps each system to its context.
• Tailwind config present → adopt its token structure and primitives.
• An existing DESIGN.md → adopt its tokens verbatim.
• Neither → scaffold from the project's conventions; Gate 3 supplies the tokens — structure them primitive → semantic → component (W3C DTCG naming, [§I](references/context-anchors.md)) so dark mode and theming stay clean, not a flat list of hex values.

---

Phase 3 — Build

Implement in the project's framework + file conventions; the code should look like the team wrote it.

• Write realistic content (not "Lorem ipsum" or "Item 1").
• One H1 per page; no restated headings; no em dashes in UI copy.
• Copy must compile — but never corrupt the apostrophe. Contractions ("you're", "we'll", "don't") break a single-quoted JS/TS string. The fix is about the string's outer quotes, never the apostrophe:
• In JSX text nodes, leave it exactly as written — Don't have an account? is already valid.
• In string literals (props, data arrays, aria-label), wrap the whole value in double quotes ("you're") or a template literal.
• NEVER replace the apostrophe with a double-quote or backtick — Don"t is a visible typo, not a fix.
• Microcopy carries the experience. High-stakes text is spe

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: LucasSantana-Dev
• Source: LucasSantana-Dev/repaint
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.