Skip to content

shinpr/claude-code-workflows / dev-skills/skills/documentation-criteria

documentation-criteria

Verified

Determines which of PRD, ADR, UI Spec, Design Doc, and Work Plan a change requires, and where each is stored. Use when deciding documentation scope, or when creating or reviewing a technical document.

references/ui-spec-template.md

View on GitHub
# [Feature Name] UI Specification

## Overview

[Purpose and scope of this UI Specification in 2-3 sentences]

### Requirement Context
- PRD path: [docs/prd/xxx-prd.md | "N/A — based on requirements analysis output"]
- Feature scope: [Which requirements this UI Spec covers]

### Design Source
| Source | Path | Version |
|--------|------|---------|
| Prototype code | [docs/ui-spec/assets/xxx/] | [commit SHA / tag] |

## Prototype Management

Prototype code is an **attachment** to this UI Spec. The canonical specification is always this document + the Design Doc.

- **Attachment path**: [docs/ui-spec/assets/{feature-name}/]
- **Version identification**: [commit SHA / tag]
- **Compliance premise**: [e.g., design system compliance, component library usage]
- **Reference strength**: [`binding` — implementation follows the attachment's rendering except where this document states otherwise | `reference` — only what this document records reaches implementation]
- **Relationship to canonical spec**: Differences between prototype and this spec are resolved in favor of this document under either strength.

## External Resources Used

Lists each external resource this feature depends on with its feature-specific identifier. Resources not used by this feature are omitted from the table.

| Resource (project-tier label) | Feature-specific identifier | Notes |
|-------------------------------|-----------------------------|-------|
| Design Origin | [feature-specific identifier] | [scope notes] |
| Design System | [components used in this feature] | [variants, customizations] |
| Visual Verification Environment | [story names / test paths / page routes] | [how this feature is rendered for review] |

## AC Traceability (Prototype)

Map acceptance criteria to prototype references, preserving existing AC IDs when present. Skip this section if no prototype is provided.

| Criterion ID / Reference | Criterion Summary | Screen / State | Prototype Reference (element ID / path) | Adoption Decision |
|-------|-----------|----------------|----------------------------------------|-------------------|
| AC-001 | [EARS AC summary] | [Screen / state name] | [element or file reference] | Adopted / Not adopted / On hold |

## Screen List and Transitions

Add a screen-transition or component-tree Mermaid diagram only when the material interaction or hierarchy stays unclear in the tables below; otherwise keep the table form.

### Screen List

| Screen ID | Screen Name | Description | Entry Condition |
|-----------|------------|-------------|-----------------|
| S-01 | [Screen name] | [Purpose] | [How user reaches this screen] |

### Transition Conditions

| Source | Destination | Trigger | Guard Condition |
|--------|------------|---------|-----------------|
| S-01 | S-02 | [User action] | [Precondition if any] |

## Component Decomposition

### Component Tree

```
[Page/Screen]
  +-- [Container Component]
  |   +-- [Presentational Component A]
  |   +-- [Presentational Component B]
  +-- [Container Component]
      +-- [Presentational Component C]
```

### Component: [ComponentName]

> Component heading uniqueness: every `Component: [ComponentName]` heading must be unique within this UI Spec. Duplicate or paraphrased headings break downstream propagation to implementation tasks.

#### State x Display Matrix

The matrix contains one row for each state supported by the requirements, approved UI direction, preserved behavior, or repository/design-system rules.

| State | Trigger | Display | Interaction / Recovery | Evidence |
|-------|---------|---------|------------------------|----------|
| [Applicable state] | [Condition that activates it] | [Rendered outcome] | [Available action or N/A] | [Requirement, UI evidence, or repository rule] |

#### Interaction Definition

| Criterion ID / Reference | EARS Condition | User Action | System Response | State Transition | Error Handling |
|-------|---------------|-------------|-----------------|-----------------|----------------|
| AC-001 | When [trigger] | [Click / input / etc.] | [Expected behavior] | [From state -> To state] | [Retry / Reset / Fallback] |

### Component: [ComponentName2]

[Repeat the applicable State x Display Matrix and Interaction Definition for each in-scope interactive component]

## Design Tokens and Component Map

### Environment Constraints

- Target browsers: [e.g., Chrome 120+, Safari 17+]
- Theme support: [e.g., light/dark, system preference]

#### Responsive Behavior

| Breakpoint | Width | Key Changes |
|-----------|-------|-------------|
| Mobile | [e.g., < 768px] | [e.g., single column, hamburger nav, 14px body text] |
| Tablet | [e.g., 768px - 1023px] | [e.g., 2-column grid, collapsed sidebar] |
| Desktop | [e.g., ≥ 1024px] | [e.g., full layout, expanded nav, sidebar visible] |

### Existing Component Reuse Map

| UI Element | Decision | Existing Component | Notes |
|-----------|----------|-------------------|-------|
| [Button] | Reuse | [components/ui/Button] | [No modifications needed] |
| [DataTable] | Extend | [components/ui/Table] | [Add sorting support] |
| [FeatureCard] | New | - | [No similar component exists] |

### Design Tokens

#### Color Roles

| Role | Token | Value | Usage |
|------|-------|-------|-------|
| Background Surface | [bg-primary] | [e.g., #FFFFFF] | [Page background] |
| Background Surface | [bg-secondary] | [e.g., #F9FAFB] | [Card, section background] |
| Text | [text-primary] | [e.g., #111827] | [Headings, body text] |
| Text | [text-secondary] | [e.g., #6B7280] | [Captions, placeholders] |
| Brand / Accent | [color-brand] | [e.g., #1A73E8] | [Primary actions, links] |
| Status | [color-success] | [e.g., #22C55E] | [Success states, confirmations] |
| Status | [color-error] | [e.g., #EF4444] | [Error states, destructive actions] |
| Border | [border-primary] | [e.g., #E5E7EB] | [Card borders, dividers] |

#### Typography Hierarchy

| Role | Font | Size | Weight | Line Height | Letter Spacing |
|------|------|------|--------|-------------|----------------|
| Heading 1 | [e.g., Inter] | [e.g., 30px] | [e.g., 700] | [e.g., 1.2] | [e.g., -0.02em] |
| Heading 2 | [e.g., Inter] | [e.g., 24px] | [e.g., 600] | [e.g., 1.3] | [e.g., -0.01em] |
| Body | [e.g., Inter] | [e.g., 16px] | [e.g., 400] | [e.g., 1.5] | [e.g., 0] |
| Caption | [e.g., Inter] | [e.g., 12px] | [e.g., 400] | [e.g., 1.4] | [e.g., 0.01em] |
| Monospace | [e.g., JetBrains Mono] | [e.g., 14px] | [e.g., 400] | [e.g., 1.6] | [e.g., 0] |

#### Spacing Scale

| Token | Value | Usage |
|-------|-------|-------|
| [spacing-xs] | [e.g., 4px] | [Inline element gaps] |
| [spacing-sm] | [e.g., 8px] | [Compact padding] |
| [spacing-md] | [e.g., 16px] | [Default component padding] |
| [spacing-lg] | [e.g., 24px] | [Section spacing] |
| [spacing-xl] | [e.g., 40px] | [Page section separation] |

#### Elevation (Depth)

| Level | Treatment | Usage |
|-------|-----------|-------|
| 0 (Flat) | [e.g., none] | [Inline elements, text] |
| 1 (Raised) | [e.g., 0 1px 2px rgba(0,0,0,0.05)] | [Cards, buttons] |
| 2 (Floating) | [e.g., 0 4px 12px rgba(0,0,0,0.1)] | [Dropdowns, popovers] |
| 3 (Overlay) | [e.g., 0 8px 24px rgba(0,0,0,0.15)] | [Modals, dialogs] |

#### Border Radius Scale

| Token | Value | Usage |
|-------|-------|-------|
| [radius-sm] | [e.g., 4px] | [Badges, chips] |
| [radius-md] | [e.g., 8px] | [Cards, inputs] |
| [radius-lg] | [e.g., 12px] | [Modals, panels] |
| [radius-full] | [e.g., 9999px] | [Avatars, pills] |

## Visual Acceptance

### Golden States
Define the key visual states that serve as acceptance benchmarks:

1. **[State name]**: [Description of what should be visually confirmed]
2. **[State name]**: [Description]

### Layout Constraints
- [Min/max width, height constraints]
- [Spacing rules between components]
- [Overflow behavior]

## Accessibility Requirements

### Keyboard Navigation

| Component | Tab Order | Key Binding | Behavior |
|-----------|-----------|-------------|----------|
| [Component] | [Order number] | [Enter / Space / Arrow] | [Expected behavior] |

### Screen Reader

| Component | Role | Accessible Name | Live Region |
|-----------|------|-----------------|-------------|
| [Component] | [ARIA role] | [aria-label / aria-labelledby] | [polite / assertive / none] |

### Contrast Requirements

| Element | Foreground | Background | Ratio Target |
|---------|-----------|------------|-------------|
| [Text element] | [Color] | [Color] | [4.5:1 for normal text / 3:1 for large text] |

## Open Items

| ID | Description | Blocking Effect | Required Owner / Evidence |
|----|-------------|-----------------|---------------------------|
| TBD-01 | [Only a decision-blocking unresolved item] | [What cannot proceed] | [Who decides or what evidence resolves it] |

Omit non-blocking unknowns from this table or state them in the relevant section. Resolve decision-blocking items before Design Doc creation.

## Update History

| Date | Version | Changes | Author |
|------|---------|---------|--------|
| YYYY-MM-DD | 1.0 | Initial version | [Name] |
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall