UI and UX kit

Build one screen or one component well. This skill owns hierarchy, states, components, motion and UX for every platform, including the car and the TV. It does not choose palettes (that is color-kit) and it does not own the token file (that is design-system-kit).

Work through every step in order. Keep a step short for a small request. Never skip silently: write Step N: skipped, because ....

Step 0: Frame

Read the signals and write the frame in a few lines: product, audience, platforms and the lead, posture (unified-brand, iOS-first, Android-first or per-platform-native), kind (page, working screen or component), context of use (hands, distance, how long a look). Show it and let the user correct it. If the read forks, ask one question with your recommendation. Guide: references/frame-and-posture.md.

Step 1: Read the system

Read the repo first: tokens, theme files, existing components, DESIGN.md, the stack files. Use what exists, by name.

• Tokens exist: use them. Invent no values.
• A palette or a mode is needed and none exists: load color-kit, then use its roles.
• A whole app or a whole token file is needed: load design-system-kit, and come back for the screens.
• Nothing exists and the scope is one screen: propose a small set of roles and say they are assumptions.

Never write a raw hex or a raw size in a component. Use roles and tokens.

Step 2: Plan the screen

Name the one question, the one finding and the list of blocks. Choose the navigation container with the tree. Decide the states owed. Pick at most one signature move. Fill templates/screen-brief.md. Guide: references/screen-anatomy.md. For one component only, skip to Step 3.

Step 3: Components

Scope the component, keep the register and the existing tokens, then specify and build it with all eight states, the geometry rules, variants and sizes, and the native equivalents for each platform. Fill templates/component-spec.md. Guide: references/components.md.

Step 4: Motion

Run the gate for every candidate: how often is it seen, and what is its purpose in one sentence? Write the thesis and the contract. Use duration and easing tokens, springs for drag, one-to-one tracking for gestures, and a reduced-motion path for every layer. Fill templates/motion-spec.md. Guide: references/motion.md. Timing table: data/motion-bands.csv.

Step 5: UX rules

Apply the rules in priority order: the task, states, accessibility, system, platform, polish, motion. Filter data/ux-rules.csv by your platforms and walk the critical and high rows. Handle forms, feedback, permissions, haptics and copy. Guide: references/ux-rules.md.

Step 6: Platform pass

Open the guide for each platform you serve and apply it. Use data/stack-notes.csv for the stack's do and don't rules and data/targets-and-sizes.csv for targets and text sizes.

For a cross-platform product, translate idioms between platforms. Never transplant them. Do not stretch a phone layout onto a tablet or a window.

Step 7: Verify

Build and run the real thing. Look at it on the right surface. Check light, dark, the largest text, reduced motion, the smallest screen and the screen reader on the main task. Ask precise questions about the render. Fix problems in one batch and look again. Run templates/preflight.md. Write ux-acceptance.csv rows and validate them with node scripts/check-acceptance.mjs ux-acceptance.csv. Guide: references/verification.md.

Step 8: Hand off

Report what changed, what you tested and on which surface, which checks were not verified, and the acceptance rows you wrote. If the work is part of a shipped product, give the rows to product-polish-workflow so they join its journey tracker. If new roles or states were needed, hand them to design-system-kit.

Rules

1. Read the room first. Frame before you draw. Name the posture.
2. One question per screen. The biggest block answers it. State the finding.
3. Use the system that exists. Tokens by name. No raw values.
4. Chrome lags content. Keep platform chrome native until the brand needs it.
5. Every state, every time. Eight for a control, and the view states for a screen.
6. Motion needs a purpose and a frequency check. Do not animate frequent actions.
7. Targets and text meet the platform minimum. Car 76 dp, TV 64 px, iOS 44 pt, Android 48 dp.
8. A gesture always has an alternative.
9. Evidence from the right surface. A browser screenshot is not native proof.
10. Driving first in a car. Two or three glances, host templates, voice, no decorative motion, and no checkout or typing.

What is in this folder

Related skills

• color-kit: owns palettes, roles, modes and contrast proof. Call it when a screen needs a new palette or a mode.
• design-system-kit: owns the token file, type, space, DESIGN.md and governance. Call it for a whole system.
• product-polish-workflow: audits and changes a shipped product and keeps the journey tracker. It takes your acceptance rows.
• prototype-wireframe: answers one open question with a throwaway before you build for real.
• tdd: test behavior of the real component first.
• verify: prove the rendered result on the real surface.
• challenge-me: stress-test the direction before you build.

Done when

• The frame and posture are written and the user agreed.
• The screen's question and finding are stated, or the component's spec is filled.
• Every state exists and uses tokens and roles.
• Every motion has a purpose, a token and a reduced-motion path.
• Platform minimums hold for every platform served.
• It was run on the right surface and the checks are listed, with Not verified items named.
• ux-acceptance.csv is valid and every row has a code anchor.