[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M753XJMBJ8VFPRCDCC1JJ9G4":3,"skill-same:01M753XJMBJ8VFPRCDCC1JJ9G4":132},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":28,"commitSha":29,"skillDirectory":30,"forksCount":14,"repositoryHtmlUrl":31,"repositoryHomepageUrl":6,"ownerHtmlUrl":32,"ownerBlogUrl":33,"ownerDescription":34,"updatedAt":35,"install":36,"resources":49},"01M753XJMBJ8VFPRCDCC1JJ9G4","ui-craft",null,"Provides guardrails for user-facing UI work: usability heuristics, accessibility floors, design-system discipline, component states, microcopy, motion, dark mode, responsive behavior, and human-AI UX. Use when designing, generating, reviewing, or refactoring visible product surfaces such as components, pages, dashboards, forms, dialogs, loading\u002Fempty\u002Ferror states, or AI interfaces. Do not use for backend-only work, infrastructure, CLI\u002FTUI design, or pure documentation editing.","haryelramalho\u002Fskills","haryelramalho","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F38708454?v=4","01M753ESC6XNS6GXGV5X9YMKGA","Haryel Ramalho","01M753ESCSPRNDTEJRVRYY1VJ0",0,"MIT","https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcurated\u002Fui-craft\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: ui-craft\ndescription: >-\n  Provides guardrails for user-facing UI work: usability heuristics,\n  accessibility floors, design-system discipline, component states, microcopy,\n  motion, dark mode, responsive behavior, and human-AI UX. Use when designing,\n  generating, reviewing, or refactoring visible product surfaces such as\n  components, pages, dashboards, forms, dialogs, loading\u002Fempty\u002Ferror states, or\n  AI interfaces. Do not use for backend-only work, infrastructure, CLI\u002FTUI\n  design, or pure documentation editing.\nmetadata:\n  author: Pedro Nauck\n  github: https:\u002F\u002Fgithub.com\u002Fpedronauck\n  repository: https:\u002F\u002Fgithub.com\u002Fpedronauck\u002Fskills\n---\n# UI Craft\n\n## The Fundamental Law\n\n```\nAI-GENERATED UI FAILS THE SAME WAYS EVERY TIME.\nVisual sameness. Weak hierarchy. Fake interactivity.\nHalf the states missing. Hex codes outside the token system.\n\"Welcome!\" microcopy that nobody asked for.\nThis skill exists so the UI being shipped is not slop.\n```\n\nUI craft is the discipline of producing user-facing surfaces that respect the user, the brand, and the medium. It is not \"make it pretty.\" It is: every visible state explicit, every interactive element reachable by keyboard, every value drawn from the design system, every word earning its place, every motion serving a purpose.\n\nA user interface is a contract with a real person. Ship slop and the contract breaks.\n\n## Required Reading Router\n\nMatch your task to the row. Read the listed files **in full before generating anything visual**. They are not appendices — they are load-bearing. Inline content in this SKILL.md is a pointer to the reference file, not a substitute for it. Files are loaded JIT (never all at once); but every row whose trigger applies to your task is mandatory, not optional.\n\n| Task                                          | MUST read                                                        |\n| --------------------------------------------- | ---------------------------------------------------------------- |\n| Any interactive widget (dialog, menu, combo)  | `references\u002Faccessibility-floor.md`                              |\n| Auditing AI-generated UI                      | `references\u002Fai-slop-patterns.md` + `references\u002Fanti-defaults.md` |\n| Designing a novel surface                     | `references\u002Fusability-foundations.md`                            |\n| Picking or extending a component pattern      | `references\u002Fcomponent-patterns.md`                               |\n| Writing or reviewing user-visible text        | `references\u002Fmicrocopy-quality.md`                                |\n| Implementing or reviewing dark mode           | `references\u002Fdark-mode.md`                                        |\n| Animation \u002F transitions \u002F motion review       | `references\u002Fmotion-patterns.md`                                  |\n| AI \u002F agent UI (chat, streaming, citations)    | `references\u002Fhuman-ai-ux.md`                                      |\n| Working with DESIGN.md or extending tokens    | `references\u002Fdesign-system-integration.md`                        |\n| Performance work \u002F pre-ship gates             | `references\u002Fperformance.md`                                      |\n| \"We need a [Linear\u002FNotion-like] X\" brief      | `references\u002Farchetypes.md`                                       |\n| No existing token system in the repo          | `references\u002Fvisual-craft.md`                                     |\n\n## Reference Index\n\nWhat each file covers (the Router above tells you *when* to load them):\n\n- `references\u002Fusability-foundations.md` — Nielsen 10 heuristics, Laws of UX, progressive disclosure, mental models.\n- `references\u002Faccessibility-floor.md` — Full WCAG 2.2 AA checklist, ARIA patterns (dialog, combobox, menu, tabs, slider, listbox), verification recipes.\n- `references\u002Fvisual-craft.md` — Typography scales, color systems, spacing rhythm, motion physics, dark mode, elevation.\n- `references\u002Fcomponent-patterns.md` — Do\u002Fdon't per component: buttons, inputs, dialogs, navigation, tables, dropdowns, tabs, popovers, toasts.\n- `references\u002Fmicrocopy-quality.md` — Full banned-vocabulary list, tone guides per surface, error\u002Fempty\u002FCTA copy rules.\n- `references\u002Fai-slop-patterns.md` — Before\u002Fafter for each of the 14 anti-slop patterns. Detection prompts. Remediation recipes.\n- `references\u002Fanti-defaults.md` — 17 literal artifacts to refuse on sight (emoji-as-icon, \"Inter\" by reflex, centred hero, placeholder names, gradient text, glassmorphism padrão, modal-as-first-thought, etc.).\n- `references\u002Fhuman-ai-ux.md` — Microsoft + IBM agent\u002FAI UI guidelines distilled.\n- `references\u002Fdesign-system-integration.md` — Canonical DESIGN.md sections, semantic tokens, shadcn\u002FRadix composition, rules-files for AI codegen.\n- `references\u002Fperformance.md` — 80ms perceived-performance threshold, font-loading zero-CLS strategy, executable pre-ship gate.\n- `references\u002Fmotion-patterns.md` — 100\u002F300\u002F500 duration rule, easing curves, Tailwind\u002FCSS\u002FFramer code, reduced-motion templates, severity-tagged anti-patterns.\n- `references\u002Fdark-mode.md` — Surface-lightness elevation, accent desaturation, semantic token strategy, dangerous combinations.\n- `references\u002Farchetypes.md` — Seven named archetypes (Bento, Command Palette, Focus Mode, Live Status, Intelligent List, Empty State Hero, Inline Editor) each with a six-slot signature contract.\n\n### Scripts\n\n- `scripts\u002Fcheck-contrast.mjs` — verify foreground\u002Fbackground WCAG AA\u002FAAA + APCA Lc. Zero-dependency, accepts hex \u002F rgb \u002F oklch. Wire into CI when token files change.\n- `scripts\u002Fdetect-token-drift.mjs` — scan source for raw hex \u002F rgb \u002F hsl \u002F oklch outside designated token paths. Reports file:line with replacement suggestion.\n- `scripts\u002Fvalidate-metadata.py` — validate this skill's `name`\u002F`description` frontmatter against the agentskills.io spec.\n\n## Tunable Design Dials\n\nThree named dials let the user steer taste without dragging the conversation through dozens of micro-preferences. Declare values before generating anything visual, and pin them in the deliverable so a future review can re-anchor.\n\n| Dial                  | Range | Default | Low end (1–3)                                | High end (8–10)                                       |\n| --------------------- | ----- | ------- | -------------------------------------------- | ----------------------------------------------------- |\n| `VISUAL_VARIANCE`     | 1–10  | 6       | Conservative, system-aligned, recognizable   | Bold, expressive, willing to diverge from the category default |\n| `MOTION_INTENSITY`    | 1–10  | 4       | Reduced\u002Futility only: state feedback         | Rich orchestration, layered materials, premium feel   |\n| `INFORMATION_DENSITY` | 1–10  | 5       | Spacious, calm, marketing-leaning            | Dense, data-heavy, dashboard-leaning                  |\n\nWhat changes at each end:\n\n- **`VISUAL_VARIANCE`** — at low values, defaults to the closest equivalent of a familiar pattern (e.g. shadcn defaults, Material 3, Apple HIG). At high values, breaks the category template deliberately — bento over grid, asymmetric over centred, branded color over neutral.\n- **`MOTION_INTENSITY`** — drives durations (low → 80–150ms only; high → up to 500ms entrances, layered easing), and unlocks premium materials (blur, mask, clip-path) at ≥ 7.\n- **`INFORMATION_DENSITY`** — drives spacing scale ramps (low → space-6\u002F8\u002F10; high → space-1\u002F2\u002F3), row heights, line-height, and chart annotation richness. High density implies tabular-nums and keyboard-first interactions.\n\nWhen the user asks for \"more bold\" \u002F \"calmer\" \u002F \"tighter\" \u002F \"looser\", translate to dial moves. Do not re-derive every other choice from scratch.\n\nCite: dial pattern adapted from `taste-skill` (Leonxlnx, open-design ecosystem).\n\n## HARD-GATE\n\n```\nDo NOT generate, modify, or approve any user-facing UI surface until:\n\n1. The brand authorities have been READ (not skimmed):\n   - DESIGN.md (root) if present\n   - Design token files (e.g. packages\u002Fui\u002Fsrc\u002Ftokens.css, theme.ts, tailwind.config.*)\n   - Frontend conventions doc (e.g. web\u002FCLAUDE.md, .cursorrules, .ai\u002Frules.md)\n   - Copy authority (e.g. COPY.md, content\u002Fstyle-guide.md)\n2. The surface's JOB is stated in one sentence (what the user is here to do).\n3. The complete STATE LIST for the surface is enumerated\n   (default, hover, active, focus-visible, disabled, loading, empty, error, success — plus any domain states).\n4. The component is known to either EXIST in the design system already\n   or is JUSTIFIED as a new addition with a token-level proposal.\n5. The SCENE SENTENCE has been written (see below). Categories are not scenes.\n6. The REGISTER has been picked: Product or Brand (see below).\n\nThis gate applies to every change — a one-line tweak, a new variant, a full page.\n\"It's just a small change\" is the most common slop excuse.\n```\n\n### Scene Sentence\n\nBefore any visual decision (dark vs light, density, color register, motion intensity), write a sentence of physical context: *who* uses this, *where*, under *what ambient light*, in *what mood*.\n\n- ❌ \"Observability dashboard\" — that is a category. It points at a thousand average answers.\n- ✅ \"SRE glances at incident severity on a 27\" monitor at 2am in a dim room — every UI element competes with a paged alert sound.\"\n- ❌ \"Marketing landing page\"\n- ✅ \"Engineering lead, 11am Tuesday, second tab over from Linear, decides in 12 seconds whether to forward this to procurement.\"\n\nIf the scene does not force the answer, add detail until it does. Most weak visual decisions come from a missing scene — the rest comes from defaults (see `references\u002Fanti-defaults.md`).\n\nCite: scene-driven decisions adapted from `impeccable` (pbakaus\u002Fimpeccable).\n\n### Register: Product or Brand\n\nTwo registers, two rule sets. Pick before generating; do not blend reflexively.\n\n| Register     | Lives in                                           | Color                                      | Type                              | Motion                                          | Bans                                              |\n| ------------ | -------------------------------------------------- | ------------------------------------------ | --------------------------------- | ----------------------------------------------- | ------------------------------------------------- |\n| **Product**  | App shells, dashboards, settings, forms, lists     | Restrained: tinted neutrals + 1 accent ≤10% | System fonts ok; fixed rem scale  | 150–250ms state feedback only; no decoration    | Decorative motion, reinvented affordances         |\n| **Brand**    | Landing pages, hero blocks, onboarding, marketing  | Committed or Drenched: 1 saturated color carries 30–60% | Display + body pairing; expressive choice | Full orchestration welcome; entrance reveals    | Generic illustration, lazy monospace as \"tech\"    |\n\nDecision rule:\n\n- The scene sentence describes a recurring task by a known user → **Product**.\n- The scene sentence describes a first impression, a deliberate impression, a campaign → **Brand**.\n- If you cannot decide, the answer is almost always **Product** — brand register is the exception.\n\nSwitching registers mid-surface is the source of half of all \"this feels off\" reactions. Lock the register and design within its rules.\n\nCite: register split adapted from `impeccable` (pbakaus\u002Fimpeccable).\n\n## The Anti-Slop Operating Loop\n\nRun every UI task through this loop in order. Skipping steps produces slop. Each step has a stop condition.\n\n### Step 1 — Load brand authorities\nRead every file listed in the HARD-GATE that exists in the repo. Treat their contents as **normative**: tokens, components, copy patterns, and naming conventions are authoritative. Never invent a value that already has a token. Never restate brand voice — quote it.\n\n**Stop condition:** If no brand authorities exist, fall back to `references\u002Fvisual-craft.md` defaults, but mark this in the deliverable as a finding: *\"Project has no DESIGN.md \u002F token system; recommend scaffolding before further UI work.\"* Continue, but expect to update this when bootstrapping happens.\n\n### Step 2 — State the surface's job\nOne sentence, written from the user's perspective. *\"The user opens this dialog to confirm destructive deletion of a project and its data.\"* Not *\"This is the delete confirmation modal.\"*\n\n**Stop condition:** If the surface has more than one job, split it. Multi-purpose surfaces are a primary source of weak hierarchy.\n\n### Step 3 — Apply the usability filter\nRun the surface through Nielsen's 10 heuristics + the load-bearing Laws of UX (Jakob, Hick, Miller, Fitts, Tesler). Identify the one or two that pose the most risk for this surface.\n\n**STOP. If this surface is novel, complex, or being audited, read `references\u002Fusability-foundations.md` in full before continuing this step.** The inline mention of \"Nielsen 10 + Laws of UX\" here is not a substitute for the reference.\n\n**Stop condition:** If the surface violates a heuristic without justification (e.g. no visible system status during a long-running action, hidden destructive primary action), redesign before continuing.\n\n### Step 4 — Enforce the accessibility floor\nWCAG 2.2 AA is the floor, not the ceiling. Gist tripwires — the floor items that catch most slop:\n\n- Text contrast ≥ 4.5:1 (≥ 3:1 for large text); non-text\u002Fstate indicators ≥ 3:1; **focus-visible** ≥ 2px and ≥ 3:1 on every interactive element.\n- Full keyboard reachability and operation (Tab, Shift+Tab, Enter, Space, Esc, Arrows per WAI-ARIA); target size ≥ 24×24 (≥ 44×44 on touch); `prefers-reduced-motion` honored.\n- Semantic landmarks + heading order; form controls programmatically labeled; errors associated via `aria-describedby` and announced via `aria-live` \u002F `role=\"alert\"`.\n\n**STOP. Read `references\u002Faccessibility-floor.md` in full before implementing or reviewing any interactive widget.** That file contains the complete non-negotiables list, the ARIA component patterns (dialog, combobox, menu, tabs, slider, listbox), and the verification recipes. The three bullets above are tripwires, not the contract.\n\n**Stop condition:** If a floor item cannot be met, that is a blocker, not a trade-off.\n\n### Step 5 — Apply visual craft\nDraw values from the design system. If the system is missing a value:\n\n- **Typography:** choose from the existing scale; never one-off a font-size\n- **Color:** use semantic tokens (`--color-bg-danger-subtle`), never raw hex\n- **Spacing:** snap to the spacing scale (typically 4\u002F8\u002F12\u002F16\u002F24\u002F32\u002F48\u002F64); no magic numbers\n- **Radius:** use the radius scale (`--radius-sm`, `-md`, `-lg`); no `border-radius: 7px`\n- **Motion:** duration 80–240ms for state, 240–400ms for entry\u002Fexit, easing per the system (`ease-out` for entry, `ease-in` for exit)\n- **Elevation:** use the elevation scale (`--shadow-1` … `--shadow-5`); no ad-hoc box-shadows\n\n**STOP. Read `references\u002Fvisual-craft.md` in full whenever the design system lacks a value you need, when there is no token system at all, or when you are extending typography \u002F color \u002F spacing \u002F motion \u002F elevation scales.** Do not invent a value inline if the reference defines a system for it.\n\n**Stop condition:** If a value cannot be drawn from the system and the gap is real, propose adding a token to DESIGN.md (see Step 9), do not inline-invent.\n\n### Step 6 — Enumerate the state matrix\nOpen `assets\u002Fstate-matrix.md`. For the component, fill every row that applies:\n\n- **default** — resting state, no interaction\n- **hover** — pointer over interactive surface (skip for touch-only)\n- **active \u002F pressed** — mid-interaction\n- **focus-visible** — keyboard focus indicator (always required for interactive)\n- **disabled** — non-interactive, ≥ 3:1 contrast for affordance, explain why if non-obvious\n- **loading** — work in progress; show progress signal and disable the trigger\n- **empty** — first-run \u002F no-data; explain what goes here and provide a primary action\n- **selected \u002F on \u002F checked** — when applicable\n- **error** — validation or async failure; specific, plain-language, recovery-oriented\n- **success** — confirmation that an action landed; transient unless audit-relevant\n\n**STOP. Read `references\u002Fcomponent-patterns.md` in full before designing or reviewing any of:** buttons, inputs\u002Fforms, dialogs\u002Fmodals, navigation, tables, cards, dropdown\u002Fcombobox, tabs, popovers\u002Ftooltips, toasts. Do\u002Fdon't rules live there, not here.\n\n**Stop condition:** Any state listed but not designed is a known slop pattern (`StateMatrixHoles` — see anti-slop table below). Design it now, not later.\n\n### Step 7 — Run anti-slop detection\nMatch the surface against the 14 named patterns in the table below **and** the literal blocklist in `references\u002Fanti-defaults.md`. Every match is a stop-and-fix, not a note.\n\nThen run the **two-level slop test**:\n\n- **First-order:** could a stranger guess the aesthetic from the *category alone*? (\"observability → dark blue\", \"AI startup → purple\", \"SaaS landing → centred hero with gradient\")? If yes, you are inside the training-data default.\n- **Second-order:** could they still guess from *category + your anti-references*? If yes, you have not escaped — you have just moved to the predictable counter-default (e.g. \"we hate gradients, so brutalist mono and stark monochrome instead\"). Both orders are trapped.\n\nEscape the trap by going back to the scene sentence and re-deriving from the specific user, moment, and physical context. Generic anti-defaults are still defaults.\n\n**STOP. Read BOTH `references\u002Fai-slop-patterns.md` (before\u002Fafter + remediation for each of the 14 patterns, plus detection prompts) AND `references\u002Fanti-defaults.md` (the 17 literal artifacts to refuse on sight — emoji-as-icon, \"Inter\" by reflex, centred hero, placeholder names, gradient text, glassmorphism padrão, modal-as-first-thought, etc.) before declaring the surface free of slop.** Anti-default detection is the failure mode this skill exists to prevent — the table below is a scorecard, not the source of truth.\n\n**Stop condition:** Any pattern hit. Any anti-default literal present without a scene-sentence justification. Fix before moving on.\n\n### Step 8 — Apply microcopy quality\nEvery visible word earns its place. Gist tripwires — the patterns that catch most slop:\n\n- **CTAs:** action verb + object (`Delete project`, not `OK` \u002F `Submit` \u002F `Click here`). **Errors:** what happened + why + how to recover, plain language, no blame. **Empty states:** explain what lives here + the one action that fills it.\n- **No AI vocabulary:** `seamless`, `delve`, `elevate`, `empower`, `unleash`, `harness`, `tapestry`, `landscape`, `journey`, `unlock the power of`. **No empty greetings:** `Welcome!`, `Hi there!`, `Let's get started!`. **No filler:** `Please`, `Note that`, `In order to` (use `To`).\n\n**STOP. Read `references\u002Fmicrocopy-quality.md` in full before writing or reviewing any user-visible text.** That file holds the full banned-vocabulary list, tone guides per surface type, and the confirmation\u002Fhelp\u002Ferror templates. The bullets above are tripwires, not the full contract.\n\n**Stop condition:** Any banned phrase appears. Replace.\n\n### Step 9 — Verify and document deltas\nBefore declaring the surface done:\n\n1. **Visually verify** in a browser at the supported breakpoints (mobile, tablet, desktop). Open DevTools, force each state in the state matrix, screenshot the ones that are not trivially default.\n2. **Keyboard-test** the full interaction: Tab order, focus visibility on every step, Esc to dismiss, Enter to commit, arrow-key navigation in composite widgets.\n3. **Contrast-check** any color pair using actual rendered values; do not trust the token name.\n4. **Reduced-motion test:** toggle `prefers-reduced-motion: reduce` and confirm no rejected motion.\n5. **Document deltas to the design system:** if a new token, variant, or component pattern was introduced, append it to `DESIGN.md` (or the relevant token file) **in the same change set**. Tokens-without-DESIGN.md updates are silent design-system drift.\n\n**STOP. Read `references\u002Faccessibility-floor.md#verification` for the per-ARIA-pattern verification recipes.** If Core Web Vitals, motion, fonts, or images are in scope for this surface, also read `references\u002Fperformance.md` for the executable pre-ship gate.\n\n**Stop condition:** Anything in this list that cannot be checked because the surface is not actually runnable is a blocker — say so in the deliverable, do not claim \"done.\"\n\n## Anti-Slop Detection Table\n\nMatch against every surface. Hits are not nits. Severity drives the response:\n\n- **Critical** — blocks merge. Accessibility, contract-level failures, broken keyboard or focus contracts.\n- **Serious** — blocks review approval. Visible UX degradation, training-data defaults, design-system drift.\n- **Moderate** — nit that polishes later — *unless* three or more accumulate on the same surface, in which case treat as Serious.\n\n| #  | Pattern              | Severity   | Symptom                                                                            | Fix                                                                                                  |\n| -- | -------------------- | ---------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |\n| 1  | VisualSameness       | Moderate   | Every block looks the same: same card, same radius, same shadow, same gray border  | Establish weight hierarchy with size + spacing + contrast; demote secondary blocks to plain text     |\n| 2  | WeakHierarchy        | Serious    | Eye lands on the wrong element first (decoration outranking primary action)        | One primary action, one focal point per view; demote decoration with neutral color and smaller scale |\n| 3  | TextOverflow         | Serious    | Long strings clip \u002F wrap badly \u002F push layout in responsive sizes                   | Test with worst-case content (long names, i18n strings 30% longer, zero data); use truncation + tooltip or wrap explicitly |\n| 4  | FakeInteractivity    | Critical   | Looks clickable, isn't (or vice versa); no hover\u002Ffocus\u002Factive states               | Match cursor + role + state styling to actual behavior; remove decorative affordances                |\n| 5  | EmojiSpam            | Moderate   | Emojis as decoration, mascots in headings, or replacing icons in the design system | Use only icons from the icon set; remove emoji from product UI unless culturally explicit            |\n| 6  | GradientCrutch       | Serious    | Gradient backgrounds carrying the entire visual identity                          | Lean on type + spacing + a restrained palette; reserve gradients for brand moments, not chrome       |\n| 7  | GlassmorphismAbuse   | Moderate   | `backdrop-filter: blur(...)` on everything; legibility damaged                     | Use blur on at most one elevated surface; keep text on solid backgrounds                              |\n| 8  | GenericIllustration  | Serious    | Same stock 3D \u002F isometric \u002F \"people pointing at laptops\" art in every empty state | Use brand-native marks or text-only empty states; explain the data, do not perform delight            |\n| 9  | DesignSystemDrift    | Serious    | Raw hex \u002F px values \u002F one-off radii instead of tokens                             | Replace with tokens; if no token exists, propose one in DESIGN.md                                     |\n| 10 | StateMatrixHoles     | Critical   | Loading \u002F empty \u002F error states missing or copy-pasted from default                 | Design each state explicitly; loading shows progress, empty explains, error recovers                  |\n| 11 | CenteredEverything   | Moderate   | Everything center-aligned by default; long text becomes a ragged column            | Left-align text by default; reserve center for short headlines, hero blocks, and dialog actions       |\n| 12 | RandomRadii          | Moderate   | `rounded-xl` here, `rounded-2xl` there, sharp corners on the third card           | Pick a radius hierarchy (chip \u002F control \u002F surface \u002F overlay) and apply consistently                   |\n| 13 | GhostFocus           | Critical   | Focus-visible removed \u002F styled identical to hover \u002F invisible against the bg       | Restore `:focus-visible`; outline ≥ 2px, ≥ 3:1 contrast, offset from the element                      |\n| 14 | MagicNumbers         | Moderate   | `width: 327px`, `margin-top: 11px`, `gap: 13px` — values not in any scale          | Snap to spacing\u002Fsize scale; rebuild layout from the grid                                              |\n\n## Red-Flag Self-Audit\n\nCatch these thought patterns and STOP:\n\n| Thought                                                       | What It Means                                              |\n| ------------------------------------------------------------- | ---------------------------------------------------------- |\n| \"The design system doesn't have this exact component\"         | DesignSystemDrift incoming — propose a token, do not improvise |\n| \"It's just an internal tool, ship it\"                         | The internal tool is where slop habits become muscle memory |\n| \"I'll add the loading state later\"                            | StateMatrixHoles — later never ships                       |\n| \"The empty state is fine with just 'No data yet'\"             | GenericIllustration sibling — explain what goes here       |\n| \"We'll skip a11y for v1\"                                      | A11y added later is a rewrite, not a polish                 |\n| \"Just add a gradient to make it pop\"                          | GradientCrutch                                              |\n| \"Center it\"                                                   | CenteredEverything — left-align text by default            |\n| \"Use 12 for the margin, looks better\"                         | MagicNumber — snap to the scale                            |\n| \"Add some emoji to make it friendly\"                          | EmojiSpam — friendliness comes from copy, not decoration   |\n| \"The user will figure it out\"                                 | Recognition over recall — they should not have to figure it out |\n| \"Looks good on my screen\"                                     | Test mobile + dense data + long strings + reduced motion   |\n\n## DESIGN.md Integration\n\nThis skill is not a DESIGN.md skill. It is a UI craft skill that respects DESIGN.md when present.\n\n**On every UI task:**\n1. **Locate.** Check repo root for `DESIGN.md`. Also check `packages\u002Fui\u002F`, `apps\u002Fweb\u002F`, `docs\u002F`, and `.ai\u002F`. Treat the first hit as authoritative.\n2. **Read.** Load it fully before generating UI. Tokens, components, and don'ts are normative.\n3. **Respect.** Never invent values that have tokens. Never override a documented don't.\n4. **Propose, don't rewrite.** When a new variant or token is genuinely needed, add it to DESIGN.md as a focused diff in the same change set as the UI work. Do not rewrite the file.\n5. **Bootstrap only when invited.** If DESIGN.md does not exist and the user wants UI work to continue, fall back to `references\u002Fvisual-craft.md` defaults and surface the gap as a finding. Defer authoring DESIGN.md to a dedicated DESIGN.md skill or workflow when one exists — do not bootstrap as a side effect of a UI ticket.\n\n**STOP. Read `references\u002Fdesign-system-integration.md` in full when reading or extending DESIGN.md, working with semantic tokens, structuring shadcn\u002FRadix composition, or writing rules-files for AI codegen.** The canonical DESIGN.md sections and token discipline live there.\n\n## When NOT To Use\n\n- Backend-only work (database, API, infra) — UI craft does not apply\n- CLI \u002F TUI design — use `tui-design`\n- Pure copy edits with no visual change — use a writing skill\n- Internal scripts and tooling with no user surface\n- Performance optimization that does not change the visual or interaction layer\n\n## Error Handling\n\n- **No brand authorities found:** fall back to `references\u002Fvisual-craft.md` defaults. Mark this in the deliverable. Do not invent brand identity silently.\n- **Surface cannot be rendered for verification:** state explicitly in the deliverable that visual verification is pending. Do not claim \"done.\"\n- **Conflicting tokens between DESIGN.md and a token file:** trust DESIGN.md; flag the divergence as a finding for the user to resolve.\n- **State matrix exceeds what is reasonable for the surface:** prune to the states the surface actually supports, but justify each pruning in the deliverable. Do not silently drop states.\n- **The skill detects a violation but the user insists on shipping it:** record the override in the deliverable as a known-slop hit with rationale. Do not pretend it is fixed.\n\n## Bottom Line\n\n```\nEvery UI surface is a contract with a user.\nRespect the user by drawing from the system.\nRespect the medium by completing every state.\nRespect the work by refusing slop.\n```\n\nFor tonal kinship with the rest of the toolkit, this skill is the UI sibling of `no-workarounds`: name the failure mode, gate the fix, document the override.\n","# UI Craft\n\n## The Fundamental Law\n\n```\nAI-GENERATED UI FAILS THE SAME WAYS EVERY TIME.\nVisual sameness. Weak hierarchy. Fake interactivity.\nHalf the states missing. Hex codes outside the token system.\n\"Welcome!\" microcopy that nobody asked for.\nThis skill exists so the UI being shipped is not slop.\n```\n\nUI craft is the discipline of producing user-facing surfaces that respect the user, the brand, and the medium. It is not \"make it pretty.\" It is: every visible state explicit, every interactive element reachable by keyboard, every value drawn from the design system, every word earning its place, every motion serving a purpose.\n\nA user interface is a contract with a real person. Ship slop and the contract breaks.\n\n## Required Reading Router\n\nMatch your task to the row. Read the listed files **in full before generating anything visual**. They are not appendices — they are load-bearing. Inline content in this SKILL.md is a pointer to the reference file, not a substitute for it. Files are loaded JIT (never all at once); but every row whose trigger applies to your task is mandatory, not optional.\n\n| Task                                          | MUST read                                                        |\n| --------------------------------------------- | ---------------------------------------------------------------- |\n| Any interactive widget (dialog, menu, combo)  | `references\u002Faccessibility-floor.md`                              |\n| Auditing AI-generated UI                      | `references\u002Fai-slop-patterns.md` + `references\u002Fanti-defaults.md` |\n| Designing a novel surface                     | `references\u002Fusability-foundations.md`                            |\n| Picking or extending a component pattern      | `references\u002Fcomponent-patterns.md`                               |\n| Writing or reviewing user-visible text        | `references\u002Fmicrocopy-quality.md`                                |\n| Implementing or reviewing dark mode           | `references\u002Fdark-mode.md`                                        |\n| Animation \u002F transitions \u002F motion review       | `references\u002Fmotion-patterns.md`                                  |\n| AI \u002F agent UI (chat, streaming, citations)    | `references\u002Fhuman-ai-ux.md`                                      |\n| Working with DESIGN.md or extending tokens    | `references\u002Fdesign-system-integration.md`                        |\n| Performance work \u002F pre-ship gates             | `references\u002Fperformance.md`                                      |\n| \"We need a [Linear\u002FNotion-like] X\" brief      | `references\u002Farchetypes.md`                                       |\n| No existing token system in the repo          | `references\u002Fvisual-craft.md`                                     |\n\n## Reference Index\n\nWhat each file covers (the Router above tells you *when* to load them):\n\n- `references\u002Fusability-foundations.md` — Nielsen 10 heuristics, Laws of UX, progressive disclosure, mental models.\n- `references\u002Faccessibility-floor.md` — Full WCAG 2.2 AA checklist, ARIA patterns (dialog, combobox, menu, tabs, slider, listbox), verification recipes.\n- `references\u002Fvisual-craft.md` — Typography scales, color systems, spacing rhythm, motion physics, dark mode, elevation.\n- `references\u002Fcomponent-patterns.md` — Do\u002Fdon't per component: buttons, inputs, dialogs, navigation, tables, dropdowns, tabs, popovers, toasts.\n- `references\u002Fmicrocopy-quality.md` — Full banned-vocabulary list, tone guides per surface, error\u002Fempty\u002FCTA copy rules.\n- `references\u002Fai-slop-patterns.md` — Before\u002Fafter for each of the 14 anti-slop patterns. Detection prompts. Remediation recipes.\n- `references\u002Fanti-defaults.md` — 17 literal artifacts to refuse on sight (emoji-as-icon, \"Inter\" by reflex, centred hero, placeholder names, gradient text, glassmorphism padrão, modal-as-first-thought, etc.).\n- `references\u002Fhuman-ai-ux.md` — Microsoft + IBM agent\u002FAI UI guidelines distilled.\n- `references\u002Fdesign-system-integration.md` — Canonical DESIGN.md sections, semantic tokens, shadcn\u002FRadix composition, rules-files for AI codegen.\n- `references\u002Fperformance.md` — 80ms perceived-performance threshold, font-loading zero-CLS strategy, executable pre-ship gate.\n- `references\u002Fmotion-patterns.md` — 100\u002F300\u002F500 duration rule, easing curves, Tailwind\u002FCSS\u002FFramer code, reduced-motion templates, severity-tagged anti-patterns.\n- `references\u002Fdark-mode.md` — Surface-lightness elevation, accent desaturation, semantic token strategy, dangerous combinations.\n- `references\u002Farchetypes.md` — Seven named archetypes (Bento, Command Palette, Focus Mode, Live Status, Intelligent List, Empty State Hero, Inline Editor) each with a six-slot signature contract.\n\n### Scripts\n\n- `scripts\u002Fcheck-contrast.mjs` — verify foreground\u002Fbackground WCAG AA\u002FAAA + APCA Lc. Zero-dependency, accepts hex \u002F rgb \u002F oklch. Wire into CI when token files change.\n- `scripts\u002Fdetect-token-drift.mjs` — scan source for raw hex \u002F rgb \u002F hsl \u002F oklch outside designated token paths. Reports file:line with replacement suggestion.\n- `scripts\u002Fvalidate-metadata.py` — validate this skill's `name`\u002F`description` frontmatter against the agentskills.io spec.\n\n## Tunable Design Dials\n\nThree named dials let the user steer taste without dragging the conversation through dozens of micro-preferences. Declare values before generating anything visual, and pin them in the deliverable so a future review can re-anchor.\n\n| Dial                  | Range | Default | Low end (1–3)                                | High end (8–10)                                       |\n| --------------------- | ----- | ------- | -------------------------------------------- | ----------------------------------------------------- |\n| `VISUAL_VARIANCE`     | 1–10  | 6       | Conservative, system-aligned, recognizable   | Bold, expressive, willing to diverge from the category default |\n| `MOTION_INTENSITY`    | 1–10  | 4       | Reduced\u002Futility only: state feedback         | Rich orchestration, layered materials, premium feel   |\n| `INFORMATION_DENSITY` | 1–10  | 5       | Spacious, calm, marketing-leaning            | Dense, data-heavy, dashboard-leaning                  |\n\nWhat changes at each end:\n\n- **`VISUAL_VARIANCE`** — at low values, defaults to the closest equivalent of a familiar pattern (e.g. shadcn defaults, Material 3, Apple HIG). At high values, breaks the category template deliberately — bento over grid, asymmetric over centred, branded color over neutral.\n- **`MOTION_INTENSITY`** — drives durations (low → 80–150ms only; high → up to 500ms entrances, layered easing), and unlocks premium materials (blur, mask, clip-path) at ≥ 7.\n- **`INFORMATION_DENSITY`** — drives spacing scale ramps (low → space-6\u002F8\u002F10; high → space-1\u002F2\u002F3), row heights, line-height, and chart annotation richness. High density implies tabular-nums and keyboard-first interactions.\n\nWhen the user asks for \"more bold\" \u002F \"calmer\" \u002F \"tighter\" \u002F \"looser\", translate to dial moves. Do not re-derive every other choice from scratch.\n\nCite: dial pattern adapted from `taste-skill` (Leonxlnx, open-design ecosystem).\n\n## HARD-GATE\n\n```\nDo NOT generate, modify, or approve any user-facing UI surface until:\n\n1. The brand authorities have been READ (not skimmed):\n   - DESIGN.md (root) if present\n   - Design token files (e.g. packages\u002Fui\u002Fsrc\u002Ftokens.css, theme.ts, tailwind.config.*)\n   - Frontend conventions doc (e.g. web\u002FCLAUDE.md, .cursorrules, .ai\u002Frules.md)\n   - Copy authority (e.g. COPY.md, content\u002Fstyle-guide.md)\n2. The surface's JOB is stated in one sentence (what the user is here to do).\n3. The complete STATE LIST for the surface is enumerated\n   (default, hover, active, focus-visible, disabled, loading, empty, error, success — plus any domain states).\n4. The component is known to either EXIST in the design system already\n   or is JUSTIFIED as a new addition with a token-level proposal.\n5. The SCENE SENTENCE has been written (see below). Categories are not scenes.\n6. The REGISTER has been picked: Product or Brand (see below).\n\nThis gate applies to every change — a one-line tweak, a new variant, a full page.\n\"It's just a small change\" is the most common slop excuse.\n```\n\n### Scene Sentence\n\nBefore any visual decision (dark vs light, density, color register, motion intensity), write a sentence of physical context: *who* uses this, *where*, under *what ambient light*, in *what mood*.\n\n- ❌ \"Observability dashboard\" — that is a category. It points at a thousand average answers.\n- ✅ \"SRE glances at incident severity on a 27\" monitor at 2am in a dim room — every UI element competes with a paged alert sound.\"\n- ❌ \"Marketing landing page\"\n- ✅ \"Engineering lead, 11am Tuesday, second tab over from Linear, decides in 12 seconds whether to forward this to procurement.\"\n\nIf the scene does not force the answer, add detail until it does. Most weak visual decisions come from a missing scene — the rest comes from defaults (see `references\u002Fanti-defaults.md`).\n\nCite: scene-driven decisions adapted from `impeccable` (pbakaus\u002Fimpeccable).\n\n### Register: Product or Brand\n\nTwo registers, two rule sets. Pick before generating; do not blend reflexively.\n\n| Register     | Lives in                                           | Color                                      | Type                              | Motion                                          | Bans                                              |\n| ------------ | -------------------------------------------------- | ------------------------------------------ | --------------------------------- | ----------------------------------------------- | ------------------------------------------------- |\n| **Product**  | App shells, dashboards, settings, forms, lists     | Restrained: tinted neutrals + 1 accent ≤10% | System fonts ok; fixed rem scale  | 150–250ms state feedback only; no decoration    | Decorative motion, reinvented affordances         |\n| **Brand**    | Landing pages, hero blocks, onboarding, marketing  | Committed or Drenched: 1 saturated color carries 30–60% | Display + body pairing; expressive choice | Full orchestration welcome; entrance reveals    | Generic illustration, lazy monospace as \"tech\"    |\n\nDecision rule:\n\n- The scene sentence describes a recurring task by a known user → **Product**.\n- The scene sentence describes a first impression, a deliberate impression, a campaign → **Brand**.\n- If you cannot decide, the answer is almost always **Product** — brand register is the exception.\n\nSwitching registers mid-surface is the source of half of all \"this feels off\" reactions. Lock the register and design within its rules.\n\nCite: register split adapted from `impeccable` (pbakaus\u002Fimpeccable).\n\n## The Anti-Slop Operating Loop\n\nRun every UI task through this loop in order. Skipping steps produces slop. Each step has a stop condition.\n\n### Step 1 — Load brand authorities\nRead every file listed in the HARD-GATE that exists in the repo. Treat their contents as **normative**: tokens, components, copy patterns, and naming conventions are authoritative. Never invent a value that already has a token. Never restate brand voice — quote it.\n\n**Stop condition:** If no brand authorities exist, fall back to `references\u002Fvisual-craft.md` defaults, but mark this in the deliverable as a finding: *\"Project has no DESIGN.md \u002F token system; recommend scaffolding before further UI work.\"* Continue, but expect to update this when bootstrapping happens.\n\n### Step 2 — State the surface's job\nOne sentence, written from the user's perspective. *\"The user opens this dialog to confirm destructive deletion of a project and its data.\"* Not *\"This is the delete confirmation modal.\"*\n\n**Stop condition:** If the surface has more than one job, split it. Multi-purpose surfaces are a primary source of weak hierarchy.\n\n### Step 3 — Apply the usability filter\nRun the surface through Nielsen's 10 heuristics + the load-bearing Laws of UX (Jakob, Hick, Miller, Fitts, Tesler). Identify the one or two that pose the most risk for this surface.\n\n**STOP. If this surface is novel, complex, or being audited, read `references\u002Fusability-foundations.md` in full before continuing this step.** The inline mention of \"Nielsen 10 + Laws of UX\" here is not a substitute for the reference.\n\n**Stop condition:** If the surface violates a heuristic without justification (e.g. no visible system status during a long-running action, hidden destructive primary action), redesign before continuing.\n\n### Step 4 — Enforce the accessibility floor\nWCAG 2.2 AA is the floor, not the ceiling. Gist tripwires — the floor items that catch most slop:\n\n- Text contrast ≥ 4.5:1 (≥ 3:1 for large text); non-text\u002Fstate indicators ≥ 3:1; **focus-visible** ≥ 2px and ≥ 3:1 on every interactive element.\n- Full keyboard reachability and operation (Tab, Shift+Tab, Enter, Space, Esc, Arrows per WAI-ARIA); target size ≥ 24×24 (≥ 44×44 on touch); `prefers-reduced-motion` honored.\n- Semantic landmarks + heading order; form controls programmatically labeled; errors associated via `aria-describedby` and announced via `aria-live` \u002F `role=\"alert\"`.\n\n**STOP. Read `references\u002Faccessibility-floor.md` in full before implementing or reviewing any interactive widget.** That file contains the complete non-negotiables list, the ARIA component patterns (dialog, combobox, menu, tabs, slider, listbox), and the verification recipes. The three bullets above are tripwires, not the contract.\n\n**Stop condition:** If a floor item cannot be met, that is a blocker, not a trade-off.\n\n### Step 5 — Apply visual craft\nDraw values from the design system. If the system is missing a value:\n\n- **Typography:** choose from the existing scale; never one-off a font-size\n- **Color:** use semantic tokens (`--color-bg-danger-subtle`), never raw hex\n- **Spacing:** snap to the spacing scale (typically 4\u002F8\u002F12\u002F16\u002F24\u002F32\u002F48\u002F64); no magic numbers\n- **Radius:** use the radius scale (`--radius-sm`, `-md`, `-lg`); no `border-radius: 7px`\n- **Motion:** duration 80–240ms for state, 240–400ms for entry\u002Fexit, easing per the system (`ease-out` for entry, `ease-in` for exit)\n- **Elevation:** use the elevation scale (`--shadow-1` … `--shadow-5`); no ad-hoc box-shadows\n\n**STOP. Read `references\u002Fvisual-craft.md` in full whenever the design system lacks a value you need, when there is no token system at all, or when you are extending typography \u002F color \u002F spacing \u002F motion \u002F elevation scales.** Do not invent a value inline if the reference defines a system for it.\n\n**Stop condition:** If a value cannot be drawn from the system and the gap is real, propose adding a token to DESIGN.md (see Step 9), do not inline-invent.\n\n### Step 6 — Enumerate the state matrix\nOpen `assets\u002Fstate-matrix.md`. For the component, fill every row that applies:\n\n- **default** — resting state, no interaction\n- **hover** — pointer over interactive surface (skip for touch-only)\n- **active \u002F pressed** — mid-interaction\n- **focus-visible** — keyboard focus indicator (always required for interactive)\n- **disabled** — non-interactive, ≥ 3:1 contrast for affordance, explain why if non-obvious\n- **loading** — work in progress; show progress signal and disable the trigger\n- **empty** — first-run \u002F no-data; explain what goes here and provide a primary action\n- **selected \u002F on \u002F checked** — when applicable\n- **error** — validation or async failure; specific, plain-language, recovery-oriented\n- **success** — confirmation that an action landed; transient unless audit-relevant\n\n**STOP. Read `references\u002Fcomponent-patterns.md` in full before designing or reviewing any of:** buttons, inputs\u002Fforms, dialogs\u002Fmodals, navigation, tables, cards, dropdown\u002Fcombobox, tabs, popovers\u002Ftooltips, toasts. Do\u002Fdon't rules live there, not here.\n\n**Stop condition:** Any state listed but not designed is a known slop pattern (`StateMatrixHoles` — see anti-slop table below). Design it now, not later.\n\n### Step 7 — Run anti-slop detection\nMatch the surface against the 14 named patterns in the table below **and** the literal blocklist in `references\u002Fanti-defaults.md`. Every match is a stop-and-fix, not a note.\n\nThen run the **two-level slop test**:\n\n- **First-order:** could a stranger guess the aesthetic from the *category alone*? (\"observability → dark blue\", \"AI startup → purple\", \"SaaS landing → centred hero with gradient\")? If yes, you are inside the training-data default.\n- **Second-order:** could they still guess from *category + your anti-references*? If yes, you have not escaped — you have just moved to the predictable counter-default (e.g. \"we hate gradients, so brutalist mono and stark monochrome instead\"). Both orders are trapped.\n\nEscape the trap by going back to the scene sentence and re-deriving from the specific user, moment, and physical context. Generic anti-defaults are still defaults.\n\n**STOP. Read BOTH `references\u002Fai-slop-patterns.md` (before\u002Fafter + remediation for each of the 14 patterns, plus detection prompts) AND `references\u002Fanti-defaults.md` (the 17 literal artifacts to refuse on sight — emoji-as-icon, \"Inter\" by reflex, centred hero, placeholder names, gradient text, glassmorphism padrão, modal-as-first-thought, etc.) before declaring the surface free of slop.** Anti-default detection is the failure mode this skill exists to prevent — the table below is a scorecard, not the source of truth.\n\n**Stop condition:** Any pattern hit. Any anti-default literal present without a scene-sentence justification. Fix before moving on.\n\n### Step 8 — Apply microcopy quality\nEvery visible word earns its place. Gist tripwires — the patterns that catch most slop:\n\n- **CTAs:** action verb + object (`Delete project`, not `OK` \u002F `Submit` \u002F `Click here`). **Errors:** what happened + why + how to recover, plain language, no blame. **Empty states:** explain what lives here + the one action that fills it.\n- **No AI vocabulary:** `seamless`, `delve`, `elevate`, `empower`, `unleash`, `harness`, `tapestry`, `landscape`, `journey`, `unlock the power of`. **No empty greetings:** `Welcome!`, `Hi there!`, `Let's get started!`. **No filler:** `Please`, `Note that`, `In order to` (use `To`).\n\n**STOP. Read `references\u002Fmicrocopy-quality.md` in full before writing or reviewing any user-visible text.** That file holds the full banned-vocabulary list, tone guides per surface type, and the confirmation\u002Fhelp\u002Ferror templates. The bullets above are tripwires, not the full contract.\n\n**Stop condition:** Any banned phrase appears. Replace.\n\n### Step 9 — Verify and document deltas\nBefore declaring the surface done:\n\n1. **Visually verify** in a browser at the supported breakpoints (mobile, tablet, desktop). Open DevTools, force each state in the state matrix, screenshot the ones that are not trivially default.\n2. **Keyboard-test** the full interaction: Tab order, focus visibility on every step, Esc to dismiss, Enter to commit, arrow-key navigation in composite widgets.\n3. **Contrast-check** any color pair using actual rendered values; do not trust the token name.\n4. **Reduced-motion test:** toggle `prefers-reduced-motion: reduce` and confirm no rejected motion.\n5. **Document deltas to the design system:** if a new token, variant, or component pattern was introduced, append it to `DESIGN.md` (or the relevant token file) **in the same change set**. Tokens-without-DESIGN.md updates are silent design-system drift.\n\n**STOP. Read `references\u002Faccessibility-floor.md#verification` for the per-ARIA-pattern verification recipes.** If Core Web Vitals, motion, fonts, or images are in scope for this surface, also read `references\u002Fperformance.md` for the executable pre-ship gate.\n\n**Stop condition:** Anything in this list that cannot be checked because the surface is not actually runnable is a blocker — say so in the deliverable, do not claim \"done.\"\n\n## Anti-Slop Detection Table\n\nMatch against every surface. Hits are not nits. Severity drives the response:\n\n- **Critical** — blocks merge. Accessibility, contract-level failures, broken keyboard or focus contracts.\n- **Serious** — blocks review approval. Visible UX degradation, training-data defaults, design-system drift.\n- **Moderate** — nit that polishes later — *unless* three or more accumulate on the same surface, in which case treat as Serious.\n\n| #  | Pattern              | Severity   | Symptom                                                                            | Fix                                                                                                  |\n| -- | -------------------- | ---------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |\n| 1  | VisualSameness       | Moderate   | Every block looks the same: same card, same radius, same shadow, same gray border  | Establish weight hierarchy with size + spacing + contrast; demote secondary blocks to plain text     |\n| 2  | WeakHierarchy        | Serious    | Eye lands on the wrong element first (decoration outranking primary action)        | One primary action, one focal point per view; demote decoration with neutral color and smaller scale |\n| 3  | TextOverflow         | Serious    | Long strings clip \u002F wrap badly \u002F push layout in responsive sizes                   | Test with worst-case content (long names, i18n strings 30% longer, zero data); use truncation + tooltip or wrap explicitly |\n| 4  | FakeInteractivity    | Critical   | Looks clickable, isn't (or vice versa); no hover\u002Ffocus\u002Factive states               | Match cursor + role + state styling to actual behavior; remove decorative affordances                |\n| 5  | EmojiSpam            | Moderate   | Emojis as decoration, mascots in headings, or replacing icons in the design system | Use only icons from the icon set; remove emoji from product UI unless culturally explicit            |\n| 6  | GradientCrutch       | Serious    | Gradient backgrounds carrying the entire visual identity                          | Lean on type + spacing + a restrained palette; reserve gradients for brand moments, not chrome       |\n| 7  | GlassmorphismAbuse   | Moderate   | `backdrop-filter: blur(...)` on everything; legibility damaged                     | Use blur on at most one elevated surface; keep text on solid backgrounds                              |\n| 8  | GenericIllustration  | Serious    | Same stock 3D \u002F isometric \u002F \"people pointing at laptops\" art in every empty state | Use brand-native marks or text-only empty states; explain the data, do not perform delight            |\n| 9  | DesignSystemDrift    | Serious    | Raw hex \u002F px values \u002F one-off radii instead of tokens                             | Replace with tokens; if no token exists, propose one in DESIGN.md                                     |\n| 10 | StateMatrixHoles     | Critical   | Loading \u002F empty \u002F error states missing or copy-pasted from default                 | Design each state explicitly; loading shows progress, empty explains, error recovers                  |\n| 11 | CenteredEverything   | Moderate   | Everything center-aligned by default; long text becomes a ragged column            | Left-align text by default; reserve center for short headlines, hero blocks, and dialog actions       |\n| 12 | RandomRadii          | Moderate   | `rounded-xl` here, `rounded-2xl` there, sharp corners on the third card           | Pick a radius hierarchy (chip \u002F control \u002F surface \u002F overlay) and apply consistently                   |\n| 13 | GhostFocus           | Critical   | Focus-visible removed \u002F styled identical to hover \u002F invisible against the bg       | Restore `:focus-visible`; outline ≥ 2px, ≥ 3:1 contrast, offset from the element                      |\n| 14 | MagicNumbers         | Moderate   | `width: 327px`, `margin-top: 11px`, `gap: 13px` — values not in any scale          | Snap to spacing\u002Fsize scale; rebuild layout from the grid                                              |\n\n## Red-Flag Self-Audit\n\nCatch these thought patterns and STOP:\n\n| Thought                                                       | What It Means                                              |\n| ------------------------------------------------------------- | ---------------------------------------------------------- |\n| \"The design system doesn't have this exact component\"         | DesignSystemDrift incoming — propose a token, do not improvise |\n| \"It's just an internal tool, ship it\"                         | The internal tool is where slop habits become muscle memory |\n| \"I'll add the loading state later\"                            | StateMatrixHoles — later never ships                       |\n| \"The empty state is fine with just 'No data yet'\"             | GenericIllustration sibling — explain what goes here       |\n| \"We'll skip a11y for v1\"                                      | A11y added later is a rewrite, not a polish                 |\n| \"Just add a gradient to make it pop\"                          | GradientCrutch                                              |\n| \"Center it\"                                                   | CenteredEverything — left-align text by default            |\n| \"Use 12 for the margin, looks better\"                         | MagicNumber — snap to the scale                            |\n| \"Add some emoji to make it friendly\"                          | EmojiSpam — friendliness comes from copy, not decoration   |\n| \"The user will figure it out\"                                 | Recognition over recall — they should not have to figure it out |\n| \"Looks good on my screen\"                                     | Test mobile + dense data + long strings + reduced motion   |\n\n## DESIGN.md Integration\n\nThis skill is not a DESIGN.md skill. It is a UI craft skill that respects DESIGN.md when present.\n\n**On every UI task:**\n1. **Locate.** Check repo root for `DESIGN.md`. Also check `packages\u002Fui\u002F`, `apps\u002Fweb\u002F`, `docs\u002F`, and `.ai\u002F`. Treat the first hit as authoritative.\n2. **Read.** Load it fully before generating UI. Tokens, components, and don'ts are normative.\n3. **Respect.** Never invent values that have tokens. Never override a documented don't.\n4. **Propose, don't rewrite.** When a new variant or token is genuinely needed, add it to DESIGN.md as a focused diff in the same change set as the UI work. Do not rewrite the file.\n5. **Bootstrap only when invited.** If DESIGN.md does not exist and the user wants UI work to continue, fall back to `references\u002Fvisual-craft.md` defaults and surface the gap as a finding. Defer authoring DESIGN.md to a dedicated DESIGN.md skill or workflow when one exists — do not bootstrap as a side effect of a UI ticket.\n\n**STOP. Read `references\u002Fdesign-system-integration.md` in full when reading or extending DESIGN.md, working with semantic tokens, structuring shadcn\u002FRadix composition, or writing rules-files for AI codegen.** The canonical DESIGN.md sections and token discipline live there.\n\n## When NOT To Use\n\n- Backend-only work (database, API, infra) — UI craft does not apply\n- CLI \u002F TUI design — use `tui-design`\n- Pure copy edits with no visual change — use a writing skill\n- Internal scripts and tooling with no user surface\n- Performance optimization that does not change the visual or interaction layer\n\n## Error Handling\n\n- **No brand authorities found:** fall back to `references\u002Fvisual-craft.md` defaults. Mark this in the deliverable. Do not invent brand identity silently.\n- **Surface cannot be rendered for verification:** state explicitly in the deliverable that visual verification is pending. Do not claim \"done.\"\n- **Conflicting tokens between DESIGN.md and a token file:** trust DESIGN.md; flag the divergence as a finding for the user to resolve.\n- **State matrix exceeds what is reasonable for the surface:** prune to the states the surface actually supports, but justify each pruning in the deliverable. Do not silently drop states.\n- **The skill detects a violation but the user insists on shipping it:** record the override in the deliverable as a known-slop hit with rationale. Do not pretend it is fixed.\n\n## Bottom Line\n\n```\nEvery UI surface is a contract with a user.\nRespect the user by drawing from the system.\nRespect the medium by completing every state.\nRespect the work by refusing slop.\n```\n\nFor tonal kinship with the rest of the toolkit, this skill is the UI sibling of `no-workarounds`: name the failure mode, gate the fix, document the override.\n",{"name":5,"metadata":24,"description":7},{"author":25,"github":26,"repository":27},"Pedro Nauck","https:\u002F\u002Fgithub.com\u002Fpedronauck","https:\u002F\u002Fgithub.com\u002Fpedronauck\u002Fskills","main","a5b533be2d244bbf3e5606e851742f0e0ba99423","skills\u002Fcurated\u002Fui-craft","https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills","https:\u002F\u002Fgithub.com\u002Fharyelramalho","linkedin.com\u002Fin\u002Fharyelramalho\u002F","Software Engineer @ SKORR •  Former Vice President of the Junior Computer Association - TecnoJr","2026-07-16 01:34:58",{"source":8,"skillName":5,"commands":37,"prompt":47,"zipAvailable":48},[38,41,44],{"tool":39,"command":40},"npx","npx skills add haryelramalho\u002Fskills --skill ui-craft",{"tool":42,"command":43},"bunx","bunx skills add haryelramalho\u002Fskills --skill ui-craft",{"tool":45,"command":46},"pnpm","pnpm dlx skills add haryelramalho\u002Fskills --skill ui-craft","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcurated\u002Fui-craft\u002FSKILL.md",true,[50,56,60,64,70,74,78,82,86,90,94,98,102,106,110,114,118,124,128],{"path":51,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":54,"sourceHtmlUrl":55},"assets\u002Fpre-ship-checklist.md","ASSET","资产文件",6422,"https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcurated\u002Fui-craft\u002Fassets\u002Fpre-ship-checklist.md",{"path":57,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":58,"sourceHtmlUrl":59},"assets\u002Fstate-matrix.md",5001,"https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcurated\u002Fui-craft\u002Fassets\u002Fstate-matrix.md",{"path":61,"resourceType":52,"resourceTypeDesc":53,"sizeBytes":62,"sourceHtmlUrl":63},"assets\u002Fui-audit-template.md",7296,"https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcurated\u002Fui-craft\u002Fassets\u002Fui-audit-template.md",{"path":65,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":68,"sourceHtmlUrl":69},"references\u002Faccessibility-floor.md","REFERENCE","参考文档",10120,"https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcurated\u002Fui-craft\u002Freferences\u002Faccessibility-floor.md",{"path":71,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":72,"sourceHtmlUrl":73},"references\u002Fai-slop-patterns.md",15971,"https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcurated\u002Fui-craft\u002Freferences\u002Fai-slop-patterns.md",{"path":75,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":76,"sourceHtmlUrl":77},"references\u002Fanti-defaults.md",14456,"https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcurated\u002Fui-craft\u002Freferences\u002Fanti-defaults.md",{"path":79,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":80,"sourceHtmlUrl":81},"references\u002Farchetypes.md",16090,"https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcurated\u002Fui-craft\u002Freferences\u002Farchetypes.md",{"path":83,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":84,"sourceHtmlUrl":85},"references\u002Fcomponent-patterns.md",17344,"https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcurated\u002Fui-craft\u002Freferences\u002Fcomponent-patterns.md",{"path":87,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":88,"sourceHtmlUrl":89},"references\u002Fdark-mode.md",12131,"https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcurated\u002Fui-craft\u002Freferences\u002Fdark-mode.md",{"path":91,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":92,"sourceHtmlUrl":93},"references\u002Fdesign-system-integration.md",13520,"https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcurated\u002Fui-craft\u002Freferences\u002Fdesign-system-integration.md",{"path":95,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":96,"sourceHtmlUrl":97},"references\u002Fhuman-ai-ux.md",12579,"https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcurated\u002Fui-craft\u002Freferences\u002Fhuman-ai-ux.md",{"path":99,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":100,"sourceHtmlUrl":101},"references\u002Fmicrocopy-quality.md",9820,"https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcurated\u002Fui-craft\u002Freferences\u002Fmicrocopy-quality.md",{"path":103,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":104,"sourceHtmlUrl":105},"references\u002Fmotion-patterns.md",12849,"https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcurated\u002Fui-craft\u002Freferences\u002Fmotion-patterns.md",{"path":107,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":108,"sourceHtmlUrl":109},"references\u002Fperformance.md",12661,"https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcurated\u002Fui-craft\u002Freferences\u002Fperformance.md",{"path":111,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":112,"sourceHtmlUrl":113},"references\u002Fusability-foundations.md",11845,"https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcurated\u002Fui-craft\u002Freferences\u002Fusability-foundations.md",{"path":115,"resourceType":66,"resourceTypeDesc":67,"sizeBytes":116,"sourceHtmlUrl":117},"references\u002Fvisual-craft.md",14297,"https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcurated\u002Fui-craft\u002Freferences\u002Fvisual-craft.md",{"path":119,"resourceType":120,"resourceTypeDesc":121,"sizeBytes":122,"sourceHtmlUrl":123},"scripts\u002Fcheck-contrast.mjs","SCRIPT","脚本",8671,"https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcurated\u002Fui-craft\u002Fscripts\u002Fcheck-contrast.mjs",{"path":125,"resourceType":120,"resourceTypeDesc":121,"sizeBytes":126,"sourceHtmlUrl":127},"scripts\u002Fdetect-token-drift.mjs",6813,"https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcurated\u002Fui-craft\u002Fscripts\u002Fdetect-token-drift.mjs",{"path":129,"resourceType":120,"resourceTypeDesc":121,"sizeBytes":130,"sourceHtmlUrl":131},"scripts\u002Fvalidate-metadata.py",2124,"https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcurated\u002Fui-craft\u002Fscripts\u002Fvalidate-metadata.py",[133,140,147,154,161,168],{"skillNo":134,"name":135,"nameZh":6,"description":136,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":137,"categories":138,"keywords":139,"publishedAt":19},"01M753YDMKSDB7320THEQ2CVW5","to-prompt-opus","Use when preparing or rewriting prompts for Claude Opus 4.8, Anthropic API agents, XML-structured prompts, long-context document work, coding agents, research synthesis, frontend\u002Fdesign tasks, or model-specific prompt optimization. Do not use for GPT\u002FOpenAI prompts or raw context packaging without Opus-specific tuning.","https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fmine\u002Fto-prompt-opus\u002FSKILL.md",[],[],{"skillNo":141,"name":142,"nameZh":6,"description":143,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":144,"categories":145,"keywords":146,"publishedAt":19},"01M753YAP95W4K2MCEAEEAV6YA","to-prompt-gpt","Use when preparing or rewriting prompts for GPT-5.5, OpenAI API agents, Responses workflows, coding agents, research synthesis, support assistants, or model-specific prompt optimization. Do not use for Claude\u002FOpus prompts or raw context packaging without GPT-specific tuning.","https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fmine\u002Fto-prompt-gpt\u002FSKILL.md",[],[],{"skillNo":148,"name":149,"nameZh":6,"description":150,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":151,"categories":152,"keywords":153,"publishedAt":19},"01M753Y700AZ0GVJDNW9Q1Q54F","plan-refactor-qa","Plans and runs qa-report before executing Compozy refactor tasks. Use when the user provides a refactor or issue slug and wants Codex to inspect the matching .compozy\u002Ftasks directory, related PRD\u002FTechSpec\u002FADR\u002Ftask artifacts, affected code, and existing tests, then invoke $qa-report with a repository-grounded prompt. Do not use to run tests, execute qa-execution, implement code, or perform post-refactor verification.","https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fmine\u002Fplan-refactor-qa\u002FSKILL.md",[],[],{"skillNo":155,"name":156,"nameZh":6,"description":157,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":158,"categories":159,"keywords":160,"publishedAt":19},"01M753XZENG0Z8S2ET75EM8CGB","multi-tool-branch-review","Orchestrates a multi-tool branch review of the current git branch against a base branch. By default it runs two independent thermo-nuclear maintainability audits, one on Codex GPT-5.5 xhigh and one on Claude Opus xhigh, then consolidates the findings into a single remediation plan via writing-plans. If the user explicitly asks for native reviews, it can add the Claude native review pass, the Codex native review pass, or both. Use when the user wants a deep cross-model review of a branch or PR before merge, or asks to review this branch with multiple tools or models. Encodes known infra failure modes and their fixes (missing Claude ACP adapter, Codex MCP auth hangs, false-positive report files, long jobs orphaned inside subagents). Do not use for reviewing a single uncommitted snippet, for non-git work, for running only one reviewer, or when the user only wants a quick lint or test run.","https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fmine\u002Fmulti-tool-branch-review\u002FSKILL.md",[],[],{"skillNo":162,"name":163,"nameZh":6,"description":164,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":165,"categories":166,"keywords":167,"publishedAt":19},"01M753XQM40XCK55BH5WPA88EW","create-pr-with-template","Create a GitHub Pull Request with gh CLI and prefer repository PR templates automatically. Use this whenever the user asks to open\u002Fcreate a PR, especially when template compliance is needed. If multiple templates exist, ask the user which template to use.","https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fmine\u002Fcreate-pr-with-template\u002FSKILL.md",[],[],{"skillNo":169,"name":170,"nameZh":6,"description":171,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":172,"categories":173,"keywords":174,"publishedAt":19},"01M753XD1NERX9S3VMYQCXHJ1Y","typescript-advanced","Master TypeScript's advanced type system including generics, conditional types, mapped types, template literals, and utility types for building type-safe applications. Use when implementing complex type logic, creating reusable type utilities, or ensuring compile-time type safety in TypeScript projects. Don't use for plain JavaScript, runtime validation libraries (Zod, Yup), or basic TypeScript syntax questions.","https:\u002F\u002Fgithub.com\u002Fharyelramalho\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fcurated\u002Ftypescript-advanced\u002FSKILL.md",[],[]]