shinpr/claude-code-workflows / dev-skills/skills/documentation-criteria
documentation-criteria
VerifiedDetermines 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.2 KB |
| references/adr-template.md | markdown | 3.1 KB |
| references/design-template.md | markdown | 19.8 KB |
| references/plan-template.md | markdown | 2.3 KB |
| references/prd-template.md | markdown | 4.7 KB |
| references/task-template.md | markdown | 1.8 KB |
| references/ui-spec-template.md | markdown | 8.8 KB |
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] |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 197k | Updated | Claude CodeCodex | Verified | Install |
| 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: 197k | Updated | Claude CodeCodex | Verified | Install |
| 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: 197k | Updated | Claude CodeCodex | Verified | Install |