This is the repo-owned contract for future Gajae-Code UI, web, dashboard, terminal, and TUI visual work. It adapts the useful OMO design-reference and visual-QA workflow without vendoring any third-party design corpus.
It is not a fifth bundled workflow skill. Gajae-Code's public workflow surface remains deep-interview, ralplan, ultragoal, and autoresearch; use this document as planning/review guidance inside those workflows or direct implementation.
Before writing broad UI code, choose and record exactly one workflow branch in the plan, issue update, PR body, or local DESIGN.md:
- Existing design system — the repository or product area already has a
DESIGN.md, component system, theme, or comparable visual grammar. Read it first and update it when the change extends the system. - Greenfield selected references — no usable system exists, so pick a small shortlist of design references before implementation. Record the exact references loaded and translate them into first-party project guidance; do not copy raw vendor files into the repo.
- Extract existing system first — the surface exists but its rules are implicit. The first deliverable is a minimal
DESIGN.mdthat extracts the current tokens, layout grammar, component anatomy, and state rules before new product screens are built.
A UI task that skips this branch selection is not ready for implementation.
New UI work must create or update the nearest product DESIGN.md before broad product-screen implementation. The document must be first-party source material for the implementation, not a screenshot dump or mood board. Include:
- Tokens — colors, typography, spacing, radii, borders, iconography, density, terminal color roles, and accessibility contrast constraints.
- Layout grammar — grids, page regions, navigation, hierarchy, rhythm, empty space, alignment, and composition rules.
- Component anatomy — named parts, slots, content rules, affordances, constraints, and when not to use the component.
- States — default, hover, active, focus, disabled, loading, empty, error, selected, expanded/collapsed, and permission/connection failure states where relevant.
- Motion and depth — animation timing/easing, transitions, shadows/elevation, overlays, focus movement, and reduced-motion behavior.
- Responsive behavior — mobile, tablet, desktop, narrow terminal, wide terminal, font scaling, wrapping, overflow, and high-density layouts.
For greenfield selected references, DESIGN.md must name the selected references and explain what was translated from each into the first-party system. It must not embed raw third-party corpus text as the system of record.
Build or update a component showcase/state harness before implementing broad product screens. The harness may be Storybook, a local route, a CLI/TUI fixture, a docs page with runnable examples, or a purpose-built screenshot fixture, but it must expose the component states needed by the product surface.
The harness must cover:
- all states listed in
DESIGN.mdthat the component supports; - representative realistic content, including long strings, empty content, error copy, and localization-sensitive text;
- mobile/tablet/desktop or narrow/medium/wide terminal layouts as applicable;
- keyboard focus and accessibility-visible states for interactive components.
Product screens can follow only after the harness proves the component vocabulary is stable enough to reuse.
Visual QA is completion evidence, not decoration. A UI story is not done until it has fresh full-surface evidence from the current branch.
Required evidence:
- Fresh capture — evidence must be generated after the current implementation, not reused from an older branch, design reference, or unrelated run.
- Full-surface coverage — capture every page, route, modal, drawer, tab, breakpoint, component state, and error/empty/loading state in scope. Sampling a few representative screenshots is not enough.
- No hidden tails — scrollable surfaces require evidence for top, middle, bottom, sticky regions, overflow behavior, and any virtualized content boundaries.
- CJK semantic line breaks block completion — Korean, Japanese, Chinese, and mixed CJK/Latin copy must not wrap in semantically broken or visually misleading ways. Bad CJK line breaks are blocking defects, not cosmetic polish.
- Independent review before done — a reviewer or review lane that did not author the implementation must inspect the full evidence set against
DESIGN.md, the component harness, and acceptance criteria before the work is marked complete. - Evidence references — PRs should link or attach the current evidence artifacts instead of describing them only in prose.
Terminal/TUI visual work must preserve terminal semantics in future helper flows. Until Gajae-Code has a dedicated helper, terminal visual-QA evidence must document the exact helper requirements and avoid flattening away the data needed for review.
A terminal/TUI evidence helper must produce, at minimum:
terminal.txtwith readable plain text;terminal-ansi.txtpreserving ANSI SGR color/style sequences and terminal control semantics needed for replay/review;terminal.htmlrendering the ANSI-styled output for browser review;- optional
terminal.pnggenerated from the styled rendering when image evidence is useful; metadata.jsoncontaining command or replay source, terminal size, font/rendering assumptions, capture timestamp, tool version, wrapping/truncation policy, and whether the artifact is from a live PTY, replay, or fixture.
Reviewers must reject terminal/TUI evidence that only contains flattened text when the change depends on color, emphasis, cursor state, layout, wrapping, or other ANSI/terminal behavior.
Do not vendor raw third-party design corpora, screenshots, brand guides, prompt packs, or critique/reference material into this repository without an explicit materializer and provenance design.
Allowed in a first PR:
- first-party
DESIGN.mdguidance written for Gajae-Code; - a small hand-written reference index that names public sources and records why they were consulted;
- pinned links, citations, or manifests that do not copy raw third-party corpus content.
Requires explicit design before inclusion:
- raw third-party corpus files;
- copied design-system text, screenshots, or asset packs;
- submodules or generated materialized corpora;
- generated screenshots committed as durable source assets.
A future materializer design must define source ownership, license/provenance metadata, pinning strategy, reproducible generation, update review, generated-file boundaries, and what artifacts are safe to attach to GitHub without committing.
For UI work, include this checklist in the PR body or equivalent review artifact:
- UI workflow branch selected: existing
DESIGN.md, greenfield selected references, or extract existing system first. -
DESIGN.mdcreated/updated with tokens, layout grammar, component anatomy, states, motion/depth, and responsive behavior. - Component showcase/state harness exists before broad product screens.
- Fresh full-surface visual evidence covers every in-scope page/state/breakpoint; no sampling.
- CJK semantic line breaks were checked and any defects were fixed before completion.
- Terminal/TUI evidence preserves ANSI semantics or documents the exact helper requirements above.
- Independent review inspected the evidence before the work was marked done.
- No raw third-party corpus was vendored without an explicit materializer/provenance design.