Communitygithub.com

ui-craft

Start here for any UI work (also called a UI craft, craft pass, polish pass, design pass, design review, UI review, or establishing a UI direction), whether building, changing, reviewing, auditing or polishing a screen, component, page, dashboard, admin app, desktop app, theme or site in any framework. It reads the client's current branding, establishes a direction as a project DESIGN.md plus a live master UI page, builds to six numbered standards (direction, layout and words, components, interaction and motion, access and resilience, proof) with plain CSS, hand-builds toasts, drawers, command menus and dialogs to library grade, and proves the result in a real browser before anything is called done.

ui-craft란 무엇인가요?

ui-craft is a Claude Code agent skill that start here for any UI work (also called a UI craft, craft pass, polish pass, design pass, design review, UI review, or establishing a UI direction), whether building, changing, reviewing, auditing or polishing a screen, component, page, dashboard, admin app, desktop app, theme or site in any framework. It reads the client's current branding, establishes a direction as a project DESIGN.md plus a live master UI page, builds to six numbered standards (direction, layout and words, components, interaction and motion, access and resilience, proof) with plain CSS, hand-builds toasts, drawers, command menus and dialogs to library grade, and proves the result in a real browser before anything is called done.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Orbit-Sling/better-uis/tree/HEAD/skills/ui-craft

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

UI craft

Two things keep AI-built UI from feeling production-level:

  1. It looks generated. The same corner roundness, grays, fonts and card grids appear whatever the brand.
  2. It isn't finished. Toasts pile up, sheets don't drag, menus break with the keyboard, and the empty, error and phone states were never built.

This skill fixes both with three things that live in each project, and six standards that live here.

In the projectWhat it is
DESIGN.mdThe brand-applied UI guide: the project's values, assets, components as they look here, "Never" list, deviations from the standards by rule ID, decisions.
Master UI pageOne live page built from the project's real CSS showing every token, every component in every state (pinnable), forms, tables, overlays and every motion with replay. Later work copies from it.
TokensOne CSS file of custom properties. Everything else uses them.
In this skillRead when
standards/S1-direction.mdEstablishing a direction: brand discovery, tokens, colour, type, motion, assets, CSS architecture, the AI look
standards/S2-layout-and-words.mdLaying out a page or app shell, writing any UI text
standards/S3-components.mdBuilding any component (29 covered, each with required states)
standards/S4-interaction-and-motion.mdKeyboard, focus, overlays, gestures, animation, progress
standards/S5-access-and-resilience.mdAccessibility, worst-case data, phones, desktop apps, themes and plugins
standards/S6-proof.mdBefore calling anything done
specs/Hand-building a toast, drawer, command menu, dialog or popover, or animated number
appendix/Depth and sources: the full directions shelf, research, library picks
standards/README.mdHow rule IDs work

Rules have IDs like S3.23.2. Cite them in plans, reviews, commits and reports.

Pick the mode first

The user asked to…ModeWhat happens
"Establish the direction", "set up the UI", or a new projectEstablishSteps 1–2 in full. The user approves the master UI page before any screen is built.
Build or change UIBuildSteps 1–4. If there's no master UI page yet, offer Establish first; it's quicker than retrofitting.
Polish existing UI that has no guideRetrofitExtract the tokens already in the code. Write DESIGN.md from them, marking the thesis and direction inferred. Build the master UI page from an inventory of the real components (step 7). Don't redesign. Then steps 3–4 on what you touch.
Review, audit, "make sure it looks good"ReviewSkip guide creation and say so. Judge against DESIGN.md, or the code's tokens and any approved design. Run S6. Report numbered findings citing rule IDs, with before-and-after evidence. Change nothing until approved.

Say which mode you're in, in one line, before starting.

Styling default: plain CSS with custom properties and @layer (templates/foundation.css). Use CSS modules or scoped styles where the framework has them. Use Tailwind only when the project already uses it. Never add Tailwind, CSS-in-JS or a component kit just to build a screen.

Step 1: Find the direction, or establish one

Find every guide: find . -maxdepth 4 -name DESIGN.md -not -path '*/node_modules/*'. Also check CLAUDE.md/AGENTS.md for a pointer.

  • Check the checkout is current. Run git status -sb and git rev-list --count HEAD..origin/HEAD. If the branch is far behind, read the guide and code from the default branch or a fresh worktree. An old checkout can carry a retired brand.
  • More than one guide: don't add another. Extend the one that covers this surface and say at the top which surfaces each governs. If two conflict, ask the user which wins.
  • Found: read DESIGN.md fully. It overrides the standards wherever it records a deviation. If a master UI page exists, build from it: copy its markup and classes, don't re-derive them.

Establishing a direction (S1 in full):

  1. Discover the current brand. Read the brand guide and any token or manifest files. Run uv run --with playwright python scripts/brand-scan.py <home> <a typical inner page> on the live site. It reports colours actually used, fonts, radius and shadow habits, existing tokens, logo and favicon, and the voice of headings and buttons. Look at its screenshots. Note where the live site drifts from the guide.
  2. Shortlist 2–3 directions from S1 (full shelf in appendix/directions.md) that fit the existing brand. Say why in one line each. A direction must fit the brand, not replace it.
  3. Let the user choose. Follow any steer they gave. In an unattended run, pick one and write "Picked by the agent, not yet confirmed" in DESIGN.md §1.
  4. Choose assets (S1.8): one icon set, fonts and an imagery style, with licences.
  5. Write DESIGN.md from templates/DESIGN.md. Discovery, thesis, tokens with measured contrast, assets and "Never" are mandatory. Mark proposed values that the brand guide doesn't cover as needing approval. If the brand deliberately uses something on the AI-look list, mark it with <!-- ai-look-ok: ... --> and record what keeps it on-brand.
  6. Put the tokens in one CSS file, starting from templates/foundation.css.
  7. Build the master UI page from templates/ui-standards.html, with the project's tokens and assets. In an existing project, inventory the real components first: list the component files and the page files, and the classes each page uses. The page's core is a "Components in use" section, one specimen per real component, built from its real markup, CSS and copy. Under each: source file, pages that use it, states, and drift found. Template components the project doesn't use go in a collapsed "Available, not used yet" section at the end. While choosing, keep the 2–3 candidates in its direction switcher. Delete the losers once one is chosen. Write component states as :is(:hover, .is-hover) so the page can pin them.
  8. Get approval: show the page live plus screenshots at 375 and 1280.
  9. Append, never overwrite, to the project's CLAUDE.md/AGENTS.md: Before building or changing UI, read DESIGN.md and build from the master UI page. Use >> or an edit, never >.

Keep the generated guide and master page in the project so later sessions can use them directly.

Step 2: Build from the page and the standards

  • Copy approved pieces from the master UI page. A component that isn't on the page gets added there first, in every state, then used.
  • For each component, read its S3 entry. If it's a solved problem, install the library S3 names or hand-build to its spec in specs/. Never improvise toasts, drawers, command menus, dialogs or comboboxes.
  • Use only tokens. No raw hex, no one-off radius, shadow or duration.
  • Build every state as you go: empty, loading, error, busy (S3).
  • Use real-looking content. Placeholder text hides layout problems.
  • Write the words to S2: buttons are verbs that name the result, errors say what to do next.

Step 3: Prove it (S6)

Run S6 and end with its report table. Key tools:

  • scripts/ai-look-scan.sh <src>, or --changed for only the files you touched. It flags AI tells and raw colours, and honours the project's ai-look-ok list. Never copy files into a temporary folder to scan them.
  • uv run --with playwright python scripts/shoot.py <urls>. It takes screenshots and flags console errors, broken requests, sideways scroll and small targets. It handles logins (--storage-state, --cookie, --http-auth-env, --password-url), clicks (--click), banners (--hide) and desktop apps (--desktop). Don't write your own screenshot script unless this one can't reach the screen, and say why if so. Then open and look at the screenshots.
  • vendor/emil-skills/skills/break-ui/SKILL.md for worst-case data.
  • After several agents fix things in parallel, run one fresh, independent review of the whole surface.

Don't call UI done until S6 passes, or the remaining items are listed as known gaps.

Step 4: Keep the direction alive

When the user corrects the look or feel, run vendor/emil-skills/skills/learn-taste/SKILL.md. It writes the correction into DESIGN.md as a rule with its reason. Update the master UI page in the same change. The same correction should never be needed twice.

Other tools in vendor/emil-skills/skills/

Emil Kowalski's design-engineering skills (MIT, pinned in vendor/emil-skills/PINNED_COMMIT):

SkillUse it for
emil-design-engA full polish review
review-animationsA strict motion review
animateBuilding any non-trivial animation
gesturesAnything dragged or flicked
mobile-nativeMaking a web app feel native on phones
prototypeLive variants with a switcher
find-animation-opportunitiesFinding where motion should go
remove-animationsFinding where motion shouldn't go
choreographSeveral things moving together
animation-performanceAnimation that drops frames
pick-ui-libraryHis curated library picks

관련 스킬