Skip to content

Open source CapCut alternative.

TypeScript

docs(agents): require light and dark UI checks

taejsa789fdce741f
diff --git a/.claude/skills/ui-quality/SKILL.md b/.claude/skills/ui-quality/SKILL.md
new file mode 100644
index 00000000..c1375f71
--- /dev/null
+++ b/.claude/skills/ui-quality/SKILL.md
@@ -0,0 +1,26 @@
+---
+name: ui-quality
+description: Build or revise Donkey UI with readable light and dark states, accessible controls, and review evidence. Use for UI additions, styling changes, and UI bug fixes.
+---
+
+# UI Quality
+
+Every UI change works in light and dark mode, including its interactive and data states. A token name alone does not prove that the rendered foreground is readable on its surface.
+
+Before editing, read the applicable frontend or native guide under `docs/guides/` and [the checks and examples](references/checks.md). For site work, inspect `site/src/app/globals.css` and the existing primitive under `site/src/components/ui/` before composing a new control. Keep the repository's data-access, styling, performance, and testing rules.
+
+```text
+surface + states + affected routes
+ ↓
+existing tokens + primitives
+ ↓
+light/dark + keyboard + viewport checks
+ ↓
+screenshots + measured results + explicit gaps
+```
+
+Record a small matrix for the affected surface: theme, viewport, UI state, route/data fixture, result, and screenshot. Exercise default, hover, focus, disabled, selected, error, loading, and empty states where the feature has them. Explain inapplicable cells. Check cold loads, navigation, and opened overlays; shared components need representative consumers on different surfaces.
+
+Fix regressions with a failing test before the fix. Use the repository's relevant tests, lint, and build; a class assertion supplements rendered checks. Retain results for the tested revision and rerun affected checks after changes. Disclose missing credentials, unavailable services, skipped states, and untested residencies in the PR. A loading shell is a loading-state result; a ready-state result requires ready content.
+
+Keep screenshots with route, theme, viewport, and state labels. Use anonymous fixtures or approved public content, inspect captures for private data, and attach the evidence to the review destination authorized by the user. This skill grants no publishing or account permissions.
diff --git a/.claude/skills/ui-quality/references/checks.md b/.claude/skills/ui-quality/references/checks.md
new file mode 100644
index 00000000..6b44908f
--- /dev/null
+++ b/.claude/skills/ui-quality/references/checks.md
@@ -0,0 +1,84 @@
+# Donkey UI checks
+
+Read these checks when adding or changing UI. Resolve colors against the surface that actually paints behind them; opacity, portals, images, and state overrides can change that surface.
+
+## Surfaces and primitives
+
+The site theme lives in [globals.css](../../../../site/src/app/globals.css). `background/foreground`, `card/card-foreground`, `popover/popover-foreground`, `primary/primary-foreground`, `secondary/secondary-foreground`, and `accent/accent-foreground` are pairs. `muted-foreground`, `border`, `input`, `ring`, and `destructive` serve their named roles; inspect their rendered contrast for the new use.
+
+The root uses the system preference until an explicit `.light` or `.dark` theme is set. Product `.app-surface` pages select `--app-background`, while public light pages use the sand background. Cold-load both kinds of surface. Check explicit light on a dark system and explicit dark on a light system when touching theme selection; exercise a preference change while the page is open.
+
+`ink`, `cream`, and `coral` are fixed brand colors. Pair fixed pastel cards with their intended ink. The note paper in [NoteComposer](../../../../site/src/cut/components/NoteComposer.tsx) keeps `NOTE_INK`; note text samples select `paper` or `dark` from [noteMarkdown](../../../../site/src/cut/lib/noteMarkdown.ts) according to their menu surface. A dark-themed menu can sit above a light note.
+
+Use [Button](../../../../site/src/components/ui/button.tsx), Input, Dialog, Popover, and DropdownMenu from the same UI directory. They carry focus, invalid, disabled, expanded, portal, and positioning behavior. Compose with `cn` and Tailwind responsive variants. Feature CSS belongs beside its owner; inline styles carry genuinely runtime values, such as data-derived CSS variables.
+
+```tsx
+// Failure: fixed ink disappears on a theme-dependent dark card.
+<button className="bg-card text-ink">Save</button>
+
+// Pair the action colors; preserve primitive focus and disabled behavior.
+<Button disabled={saving} aria-busy={saving}>Save</Button>
+
+// Pair the surface and its content; choose hint contrast on this surface.
+<section className="border border-border bg-card text-card-foreground">
+ <p className="text-muted-foreground">Choose a file</p>
+</section>
+```
+
+For the donkey mark, reuse [DonkeyMark](../../../../site/src/components/DonkeyMark.tsx) and the [backlit guide](../../../../docs/guides/backlit-icon.md). Check its fitted size and toolbar treatment; preserve the top artwork's fills and layer order. For native UI, use the platform's semantic colors and existing controls, then apply the same state and evidence matrix.
+
+## State matrix
+
+Run each applicable row in both themes at a wide desktop viewport and a narrow supported viewport. Test around the component's actual responsive breakpoint, short height, long labels, and 200% zoom. Record actual viewport dimensions. Preserve `embed=chatgpt` visibility gates when the affected UI is embedded.
+
+| State | Action and observable result |
+| --- | --- |
+| Default | Read labels, body, hints, icons, and meaningful boundaries on every surface. Inspect inline code, links, images, and prose inversion. |
+| Hover | Move onto text, icon, and nested action; check the final background/foreground pair and stable dimensions. |
+| Focus | Tab and Shift+Tab through controls; ring stays visible and unclipped. Enter/Space activates the expected action. |
+| Disabled | Reach the prerequisite that disables the action; activation stays blocked and the reason remains understandable. |
+| Selected | Toggle the state; check selected text/icon/border and `aria-pressed`, `aria-selected`, or checked semantics appropriate to the control. |
+| Error | Trigger a safe validation failure; show an error message and connect it with `aria-describedby` and `aria-invalid` where appropriate. |
+| Loading | Use a controlled pending fixture; the skeleton, label, progress, and cancellation remain understandable without layout jumps. |
+| Empty | Use zero items; the explanation and available next action remain readable. |
+
+Use labels for inputs and accessible names for icon-only controls; a tooltip supplements the name. Use the native element or existing primitive for its role. Confirm dialog title, focus entry, Escape dismissal where appropriate, focus containment, and return to the trigger. Arrow-key menu navigation must agree with its roles. Communicate errors, selection, and chart series through text or shape as well as color.
+
+## Contrast measurement
+
+Use the browser's computed foreground/background values and include opacity and every translucent ancestor. Resolve transparent surfaces to the painted background; include scrims and image regions under text. Inspect computed placeholder, hover, focus, and selected styles as separate samples. Measure with the available browser contrast tooling or a luminance calculation; record the sampled pair and ratio when contrast is at issue.
+
+The [WCAG text target](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) is 4.5:1 for normal text, including hints and hover text; large text uses 3:1 (24 CSS px regular or 18.67 CSS px bold). [Essential control/graphic indicators](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) use 3:1 against adjacent colors. Inactive controls have a contrast exception; keep their purpose and disabled explanation usable. Decorative separators need no arbitrary contrast increase. Check [visible keyboard focus](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html) on the adjacent surfaces. Existing tokens and screenshots support inspection; neither establishes a whole-page accessibility pass.
+
+```tsx
+// Failure: a hover override can break an otherwise readable pair.
+<Button variant="ghost" className="hover:text-ink">Continue</Button>
+
+// The primitive pairs hover foreground/background in both themes.
+<Button variant="ghost">Continue</Button>
+
+// Failure: no keyboard role, focus behavior, or accessible name.
+<div onClick={onClose}><X /></div>
+
+<Button size="icon" variant="ghost" aria-label="Close" onClick={onClose}>
+ <X aria-hidden="true" />
+</Button>
+```
+
+## Overlays, charts, and canvas
+
+Open portaled menus and modals through their triggers. Inspect the portal root: note-paper inheritance and a local theme wrapper may stop at the portal boundary. Shared Dialog uses `bg-popover text-popover-foreground`; keep its scrolling body and positioner so small heights remain usable. Inspect tooltips, nested menus, selected options, validation messages, and backdrops separately.
+
+Canvas pixels and chart library fills do not inherit text utilities. Inspect the actual renderer and its palette; this repo has no shared `ui/chart` primitive to assume. Check axes, tick labels, legend, tooltip, selected series, grid boundaries needed to read data, and empty/loading results. Repaint a theme-dependent renderer after a theme change without adding per-frame style reads. Preserve intentional media colors in the preview and exported artwork; theme the surrounding editor chrome. Provide accessible DOM controls and an equivalent text/table summary for data that only the drawing conveys. Preview/timeline rendering changes run the performance checks required by AGENTS.md.
+
+## Evidence
+
+Capture the rendered state after it settles, including keyboard focus and opened overlays. A useful record looks like:
+
+```text
+Route Theme Viewport State Result Evidence
+/app/library dark 1280x800 empty checked library-dark-empty.jpg
+/app/library light 390x844 error not tested backend unavailable
+```
+
+Use route templates and data-state labels to define coverage; one example slug does not cover every article or project. Next may retain hidden routes in React Activity, so a document-wide scan must filter for actual visibility. A skeleton capture establishes only the loading state. Summaries name untested themes, states, viewports, residencies, real integrations, and fixture limitations. Review screenshots for names, email addresses, project media, browser chrome, tokens, and notifications before publishing; attach evidence with captions and explicit exceptions.
diff --git a/AGENTS.md b/AGENTS.md
index 33ac8ff7..27679673 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -16,6 +16,10 @@ Performance comes first. Everything we ship has to be fast on the machines peopl
- Every cache is bounded in bytes through the memory budget (`site/src/cut/lib/memoryBudget.ts`), and every reader, decoder and canvas is closed by the code that opened it.
- Measure. A preview or timeline change runs the perf evals (`npm run eval:cut-perf`, `eval:cut-perf-lowend`) before it ships, and the summary says what moved.
+## UI Quality
+
+Every UI addition or change accounts for dark mode. Read the [UI Quality skill](.claude/skills/ui-quality/SKILL.md) and verify text, icons, and control states in light and dark themes.
+
## Site Project
Before changing `site/` UI, routes, API handlers, or data access patterns:
diff --git a/CLAUDE.md b/CLAUDE.md
index 33ac8ff7..27679673 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -16,6 +16,10 @@ Performance comes first. Everything we ship has to be fast on the machines peopl
- Every cache is bounded in bytes through the memory budget (`site/src/cut/lib/memoryBudget.ts`), and every reader, decoder and canvas is closed by the code that opened it.
- Measure. A preview or timeline change runs the perf evals (`npm run eval:cut-perf`, `eval:cut-perf-lowend`) before it ships, and the summary says what moved.
+## UI Quality
+
+Every UI addition or change accounts for dark mode. Read the [UI Quality skill](.claude/skills/ui-quality/SKILL.md) and verify text, icons, and control states in light and dark themes.
+
## Site Project
Before changing `site/` UI, routes, API handlers, or data access patterns: