DOCSEARCHbyAlgolia
Submit Docs

UI Skills

repository·main·Indexed 26 days ago

https://github.com/ibelick/ui-skills

A specialized toolkit for Design Engineers providing structured UI skill sets for agents to perform UI-related tasks. It includes a CLI for managing skill sets, the `baseline-ui` skill for enforcing opinionated constraints on spacing, typography, and layout, and the `create-design-md` skill for documenting design languages and tokens in a DESIGN.md file.

Tokens
13.9K
Snippets
21
Records
75
Agent score
92%

What's inside ui-skills

  2. Use the create-design-md skill

    main

    The create-design-md skill is used to create or update a DESIGN.md file for a product or website. This document records the design language, visual system, and design tokens. It is used to provide persistent UI context to coding agents or to reconstruct a design system from a public website.

    Key Constraints:

    • Modify only DESIGN.md. Do not change product source, dependencies, or configuration.
    • Do not copy every discovered token; only record the governing design language.
    • Do not convert local styling or visual preferences into product intent.

  3. Use the fixing-motion-performance command

    main

    You can use the fixing-motion-performance command to audit or apply animation performance constraints to your UI work.

    • /fixing-motion-performance: Apply these performance constraints to any UI animation work in the current conversation.
    • /fixing-motion-performance <file>: Review a specific file against the performance rules. The tool will report:
      • Violations (quoting the exact line or snippet)
      • Why it matters (a short explanation)
      • A concrete fix (code-level suggestion)

    Note: Do not migrate animation libraries unless explicitly requested. Apply rules within the existing stack.

  4. Apply interaction and layout constraints with baseline-ui

    main

    Adhere to these interaction and layout standards:

    • Destructive Actions: MUST use an AlertDialog for irreversible actions.
    • Loading States: SHOULD use structural skeletons.
    • Viewport/Safe Areas: NEVER use h-screen; use h-dvh instead. MUST respect safe-area-inset for fixed elements.
    • Inputs: NEVER block paste functionality in input or textarea elements.
    • Errors: MUST show errors adjacent to the action that triggered them.
    • Z-Index: MUST use a fixed z-index scale; do not use arbitrary z-* values.
    • Sizing: SHOULD use size-* for square elements instead of separate w-* and h-* classes.

  5. Apply typography and design constraints with baseline-ui

    main

    Use these standards for typography and visual design:

    Typography

    • Text Wrapping: MUST use text-balance for headings and text-pretty for body/paragraphs.
    • Data: MUST use tabular-nums for numerical data.
    • Density: SHOULD use truncate or line-clamp for dense UI.
    • Spacing: NEVER modify letter-spacing (tracking-*) unless explicitly requested.

    Design

    • Gradients: NEVER use gradients (especially purple or multicolor) unless explicitly requested.
    • Effects: NEVER use glow effects as primary affordances. NEVER animate large blur() or backdrop-filter surfaces.
    • Shadows: SHOULD use Tailwind CSS default shadow scale unless requested otherwise.
    • Empty States: MUST provide one clear next action for empty states.
    • Colors: SHOULD limit accent color usage to one per view and use existing theme/Tailwind tokens before introducing new ones.

  6. UI Best Practices (Do's and Don'ts)

    main

    Ensure your implementation follows these accessibility and aesthetic rules:

    • DO: Provide visible focus states.
    • DO: Respect prefers-reduced-motion.
    • DO: Provide one clear action in empty states.
    • DON'T: Use glow, gradients, or decorative colors when neutral styling is sufficient.

  8. Choose between Repository and URL modes for DESIGN.md

    main

    When using create-design-md, you must choose the appropriate mode based on available access:

    Repository Mode

    Use when a local product repository is available. The DESIGN.md is created or updated at the root of the selected product. This mode is preferred as it can establish normative values, token names, and documented rationale.

    URL Mode

    Use when only a public URL is provided. This mode reconstructs a DESIGN.md draft in the current workspace by inspecting the DOM, computed styles, and stylesheets at desktop and mobile widths.

    Note: URL mode can only establish observable visual patterns and computed values; it cannot establish internal token names or undocumented rationale. If rendered inspection is unavailable, you must ask for screenshots or source files.

  9. Validate DESIGN.md with lint and export

    main

    After writing a DESIGN.md file, perform structural linting and a compatibility export to ensure the document adheres to the schema and can be correctly transformed for your target environment.

    1. Linting

    Run the structural linter:

    npx @google/design.md lint DESIGN.md

    2. Exporting

    Run a compatibility export using your target format:

    npx @google/design.md export --format <format> DESIGN.md

    3. Verification

    Inspect the export output. Every populated frontmatter category must emit its corresponding token category in the export. If a category is missing from the export, the document is invalid and must be rewritten.

    For css-tailwind targets, verify the following mappings:

    • colors $\rightarrow$ --color-*
    • typography.<name>.fontFamily $\rightarrow$ --font-*
    • typography.<name>.fontSize $\rightarrow$ --text-*
    • rounded $\rightarrow$ --radius-*
    • spacing $\rightarrow$ --spacing-*

    Note: If typography is populated but the export lacks --font-* or --text-* tokens, the document is invalid.

    npx @google/design.md lint DESIGN.md
npx @google/design.md export --format <format> DESIGN.md

  10. Report UI findings using the standard template

    main

    Once findings are vetted, report them using the following structure. Order findings by confidence, user impact, reach, and cost. Stop after a maximum of three findings.

    ## Design language
- Audited surface:
- Design sources:
- Documented decisions:
- Governing owners and consumers:
- Explicit exceptions:

## Findings
| # | Problem | Evidence | Proposed change | Scope | Confidence |
| --- | --- | --- | --- | --- | --- |

## Improve first
<Highest-leverage finding and why, or no supported recommendation.>

    Requirements:

    • Every row in the table must include the Confidence column.
    • If no findings survive, use: No supported findings were found. under ## Findings and No supported recommendation. under ## Improve first.
    • After reporting, ask the user which findings to turn into implementation plans.

  12. Specify implementation changes for selected findings

    main

    When a user selects a finding to be fixed, write one self-contained plan per selected change.

    Workflow:

    1. Re-open cited sources and record the current commit.
    2. Identify exact reusable primitives and exemplars.
    3. Trace all affected surfaces.
    4. Reconcile with existing plans instead of duplicating them.

    Constraint: Do not invent values. If the repository provides a token or component contract, use it. Only introduce a new primitive if you can prove the existing system cannot express the decision.