do-wdr-ui-component

name	do-wdr-ui-component
description	Implement CSS-only UI components for the do-web-doc-resolver design system. Use when creating new components, fixing component styles, or implementing GitHub issues tagged design-system/frontend in cli/ui/. Triggers include "create component", "implement badge/tooltip/modal", "add CSS for", "design system component", or any task involving cli/ui/components/. Covers token patterns, BEM naming, accessibility, dark mode, and the wave-based GitHub issue implementation workflow.
allowed-tools	Bash(git:*), Read, Write, Edit, Glob, Grep

WDR UI Component Development

CSS-only components for the do-web-doc-resolver developer-first design system.

When to use

• Creating a new component CSS file in cli/ui/components/
• Implementing a GitHub issue tagged design-system or frontend
• Fixing component styles, accessibility, or dark mode issues
• Adding provider-specific badge variants

Component structure

Each component is a single flat .css file max 200 lines. Structure:

components/
├── badge.css
├── button.css
├── {component}.css     ← new components go here

File template

:root {
  --do-wdr-{component}-{property}: var(--do-wdr-{semantic-token});
  --do-wdr-{component}-{variant}-{property}: var(--do-wdr-{semantic-token});
}

.do-wdr-{component} { /* base */ }
.do-wdr-{component}--sm { /* size */ }
.do-wdr-{component}--md { /* size */ }
.do-wdr-{component}--lg { /* size */ }
.do-wdr-{component}--success { /* color variant */ }
.do-wdr-{component}__element { /* sub-element */ }
.do-wdr-{component}:focus-visible { outline: 2px solid var(--do-wdr-border-focus); outline-offset: 2px; }

@media (prefers-reduced-motion: reduce) {
  .do-wdr-{component} { transition: none; animation: none; }
}

Token naming

--do-wdr-{component}-{element}-{variant}-{state}
--do-wdr-button-primary-bg-hover
--do-wdr-badge-provider-exa-bg
--do-wdr-kv-key-color

Required semantic tokens (from tokens/design_tokens.css)

• Surfaces: --do-wdr-surface-bg, --do-wdr-surface-bg-elevated, --do-wdr-surface-bg-muted
• Text: --do-wdr-text-primary, --do-wdr-text-secondary, --do-wdr-text-tertiary
• Borders: --do-wdr-border-default, --do-wdr-border-subtle, --do-wdr-border-focus
• Signals: --do-wdr-signal-success, --do-wdr-signal-warning, --do-wdr-signal-error, --do-wdr-signal-info
• Signal BGs: --do-wdr-signal-success-bg, --do-wdr-signal-warning-bg, --do-wdr-signal-error-bg, --do-wdr-signal-info-bg
• Interactive: --do-wdr-interactive-bg, --do-wdr-interactive-bg-hover, --do-wdr-interactive-bg-subtle
• Spacing: --do-wdr-space-1 through --do-wdr-space-16
• Typography: --do-wdr-font-sans, --do-wdr-font-mono, --do-wdr-text-xs through --do-wdr-text-3xl
• Motion: --do-wdr-transition-colors, --do-wdr-duration-fast, --do-wdr-ease-out
• Data: --do-wdr-data-row-alt, --do-wdr-data-row-hover, --do-wdr-data-row-selected

Accessibility requirements

Every component MUST have:

1. focus-visible outline (2px --do-wdr-border-focus, offset 2px)
2. prefers-reduced-motion: reduce disabling all animations
3. Semantic HTML where applicable (dl/dt/dd, role=progressbar, aria-describedby)
4. No content conveyed by color alone

Implementation workflow

1. Read the GitHub issue body for requirements and design reference
2. Read tokens/design_tokens.css for available semantic tokens
3. Read 1-2 existing components (e.g., button.css, badge.css) for conventions
4. Write the component CSS file using Write tool
5. Update components/README.md — replace issue link with file reference
6. Commit: git add cli/ui/components/{name}.css cli/ui/components/README.md && git commit -m "feat(ui): implement {Component} — issue #{N}"

If git commands fail, follow the retry sequence before escalating: stash → abort rebase → abort merge → fetch main → retry. Never retry more than 3 times.

References

Topic	File
Design tokens	references/design-tokens.md
Accessibility requirements	references/accessibility.md

Anti-patterns (never do these)

• Adding comments to CSS code
• Animating layout properties (width, height, margin) — transform/opacity only
• Using raw primitive tokens — always use semantic tokens
• Exceeding 200 lines per file
• Generic loading spinners without context
• Decorative animation or bouncing dots