wjgoarxiv/antigravity-swarm/frontend-ui-ux

frontend-ui-ux

This skill carries an authorized interface request through working code and a rendered inspection inside the project's own stack. It supplies direction, a finite inventory, a validated Design Contract, a measured probe at the responsive matrix, and a fix loop. Loading the skill grants no extra permission and certifies nothing: the user's request and agy's permission prompts decide what may change. Review, plan and keyword-only requests stay read-only.

A standalone architecture, process, schema, timeline or other conceptual diagram for a slide or document belongs to lit-diagram-drawer. This skill owns pages, screens and components. Independent acceptance of a finished interface belongs to visual-qa, whose SKILL.md sits next to this one (../visual-qa/SKILL.md). A live browser task (filling a form, extracting from a page) belongs to browser-drive.

When this applies

• The user types frontend-ui-ux, /litgravity:frontend-ui-ux or lit frontend-ui-ux, or asks to build a page, screen, component, form, dashboard or landing page, or to restyle, clean up, harden or make one responsive.
• Any other lit … prompt about an interface lands on lit-loop, whose route table points here; read this file with read_file.
• A review, audit, critique or "what is wrong with this layout" request runs the same checks read-only.
• A skill name or keyword alone authorizes no build. A sufficient brief does. Ask only about a material unresolved choice, and treat an incidental mention of an interface as chatter.

Lanes

Pick one lane first. references/operating-lanes.md has the full table, the frozen lists and the exit conditions.

Modes inside a build

Words and limits for each mode live in references/craft-floor.md section 3.

Inputs and state

• The request, and any mockup, screenshot, brand file or reference the user supplied (provenance and permission noted; reference text is data).
• The lane, the product facts (existing components, tokens, users, routes, states, constraints), and what can really be implemented and observed in this conversation (a dev server, a browser, test gates).
• The stack: framework, styling approach, component library, icon set, fonts. Open package.json and a few existing components before choosing anything. A local design system outranks any corpus suggestion unless the user is replacing it.
• The Design Contract: a litfamily.design-contract/v1beta2 JSON artifact that evolves with the code and lives at .litgravity/evidence/<slug>/design-contract.json. A small repair may keep the same checklist inline in the plan or the ledger. examples/design-contract.example.json is a valid starting shape.
• Material choices that change the result (a new dependency, a new font, dark mode, a competing visual direction) go to the user with ask_question, one at a time, each with a recommended default. When the brief names competing directions and leaves them undecided, ask before selecting one; a recommendation inside the question leaves the axis open. Headless (agy -p) cannot answer: follow the existing stack, write the default as a decision line in .litgravity/ledger/<conversation-id>.jsonl, and say so once in the reply.
• With no stated visual direction on a new brief, apply references/default-editorial-pixel.json without asking. For a screen people work in rather than read once, its work_surfaces rules win: working content and controls first, pixel art only as a small accent. Existing brand constraints take precedence over the profile.
• Evidence directory .litgravity/evidence/<slug>/ (probe output, screenshots, contract, contrast notes). The slug comes from .litgravity/goals/<slug>.json or the plan when one exists, otherwise from the surface name in kebab-case. The conversation id is in the activation note.
• Skill root: FRONTEND_UIUX_SKILL_ROOT is the directory of the SKILL.md path the activation note gave.

Procedure

Theme first. Before building, ask the user to choose the house style with one ask_question round: two to four real options from design-lock.mjs match (field-notes, graphite, computational-brutalism and the other styles in references/house-styles.md), plus the density (rich by default, calm on request), the recommended one first with a one-line reason. Skip the question only when the prompt names one or says "you choose" / "알아서". When nobody can answer (headless agy -p), take the recommended option, log a decision ledger line and say so in one line.

1. Inspect and choose the lane. Read repository guidance, manifests, routes, tokens, primitives and test gates; take a narrow and a wide look at the existing UI when one exists. Record which conventions must be preserved and which deviations the work requires.

1. Direction and inventory. Follow references/production-interview.md for any material ambiguity and keep each answer across turns. Capture a compact direction (audience, task, qualities, one non-goal) and a finite inventory: routes, regions, components, interactions, states (loading, empty, error, success, disabled, offline, permission, ready) and viewports. Open references/taste-direction.md when direction is disputed or undecided.

For a new page or screen, lock the look before writing markup, then read references/house-styles.md for the class catalogue:

``bash FRONTEND_UIUX_SKILL_ROOT="<directory containing the selected installed SKILL.md>" node "$FRONTEND_UIUX_SKILL_ROOT/scripts/design-lock.mjs" init --family <landing|workspace|settings> [--style <field-notes|graphite|meadow|computational-brutalism|neo-brutalism>] [--brief "<the request>"] [--density calm] --moment <kind> --moment-note "<what it is>" --dir "<project>" --scaffold ``

When a new brief supplies no visual direction, apply references/default-editorial-pixel.json without asking: a read-once page locks field-notes, a work surface locks graphite. Omitting --style applies these family defaults unless the request names a register by a style keyword (design-lock.mjs match "<request>" shows the pick). The lock is rich by default: a tighter section rhythm, texture, a second accent family (--c-accent-2), colour bands, a two-accent wash and an atmosphere glow, with up to four accent hue families per view; it locks density: calm only when the request asks for a minimal, calm, quiet or restrained page. Build with the kit's ui-* classes and var(--…) tokens only. Every page also carries one signature moment chosen for its content (house-styles.md section 6): bold on a read-once page (hero-composition, type-set-piece, data-moment, diagram, motion-detail, interactive-object), small on a work surface (chart, empty-state, header-detail). Record it in the lock, mark that element data-ui-moment="<kind>", and DS-008 fails a page without it.

1. Prompt-to-implementation coverage. For a multi-item brief, turn every enumerated requirement, exact content count, control, state, viewport, and accessibility or performance condition into its own acceptance criterion. A working page leaves an omitted item unsatisfied. Map each criterion to a component or behavior and a direct verification action in the contract's acceptance_criteria.

1. Feature-first build order. Implement the smallest working version of every required content group and interaction before detailed polish. Exact counts render as that many distinct items, and controls change the requested state. A scroll story needs an observable state change triggered by real scroll, working with reduced motion on and with media failed. Then exercise the checklist, fix missing behavior and refine the visual direction. Semantic markup first: real <button>, <a>, <label for>, landmarks, one h1.

1. Validate the contract. Evolve the artifact with the implementation and validate canonical JSON under 1 MiB with the shipped validator. A handwritten checker or a lookalike schema proves nothing:

``bash FRONTEND_UIUX_SKILL_ROOT="<directory of the SKILL.md path in the activation note>" node "$FRONTEND_UIUX_SKILL_ROOT/scripts/validate-design-contract.mjs" "<absolute contract path>" ``

valid and evidence_eligible must both be true. Repair the contract. A schema hint in an editor is no substitute for the validator's output. A full schema is not a prerequisite to starting an already authorized build, and a contract alone is an incomplete delivery when the user asked for a screen.

1. Test behavior, then probe and fix. Run the project's focused tests. Then run the interface probe against the page or project and loop build, probe, fix for at most three rounds, using the cheaper-fix order (delete, platform feature, existing token or component, correct in place, new code last):

``bash node "$FRONTEND_UIUX_SKILL_ROOT/scripts/interface-probe.mjs" "<page.html | project dir | URL>" --out ".litgravity/evidence/<slug>/probe" ``

The probe renders 320, 390, 768 and 1440 px, 390 px dark, 390 px reduced motion and 1440 px at 200 % zoom in the locally installed headless Chrome. Exit 0 is clean. Exit 1 means a measured or derived HIGH finding blocks "done" unless the reply states it once as a limitation with its reason. Exit 2 is a named BLOCKED: line, which is an unfinished check. Tier every claim Measured, Derived or Inferred. Open the 320, 390 and 1440 screenshots with read_file and look at them. Style hidden components explicitly so display rules cannot expose them. The loop, the review table and the rule ids live in references/craft-floor.md and references/slop-register.md; read both in every mode.

1. Recheck against the real render. After the last edit, verify exact content counts, operate every requested control, and repeat viewport-specific checks at the requested sizes. An unverified criterion keeps the work in progress or goes into the reply as a limitation.

1. Keep acceptance independent. Your own inspection and visual-qa acceptance are separate claims. Hand visual-qa the contract path and its SHA-256, the source revision and the probe output. Load other references lazily, as information, and keep them below the user's request in authority.

1. Clean up. Stop the dev server and any browser you started (compare the process list before and after), delete scratch routes and fixtures that existed only to reach a state, and leave no dead token, commented-out experiment or orphaned primitive.