docs: restructure DESIGN.md into Geist-inspired foundations + docs/ui product rules - #707
Merged
Merged
Conversation
JArmandoAnaya
pushed a commit
that referenced
this pull request
Aug 21, 2026
docs: restructure DESIGN.md into Geist-inspired foundations + docs/ui product rules
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
Documentation-only restructuring of the frontend design documentation.
DESIGN.mdis rewritten as a concise Geist visual-foundations and interaction contract (Purpose, Philosophy, Foundations, Component Principles, Responsive, Interaction, Accessibility, Content and Copy, Implementation Boundaries — 1453 → 437 lines). Every product rule it used to hold is relocated, not deleted:docs/ui/product-principles.md— data-first, density on data surfaces, action-forward screens, never-disable-without-explanation, blast-radius confirmations, the authoritative product status mapping, number formatting, list/section rules, tabs, the Home and project-view screen rules, component contracts, and the current layout specifics (page/dialog widths).docs/ui/navigation.md— ancestor chains and breadcrumbs, the rail's membership rule and widths, URL state ("not everything selectable is a place"), Back semantics, callbacks-not-routes.docs/ui/annotator.md— the whole annotation-workspace contract: top bar zones, side panel regions, tool strip, frame gallery, zoom and the device model, read-only mode, thestage, shape rendering, provenance and confidence rules.docs/architecture/frontend/ui-core.md— gains the Libraries section (technology constraints moved out of the visual contract).CONTRIBUTING.md,docs/README.md,docs/ui.md,docs/annotations.md, architecture READMEs, two.agents/skillsfiles; the three new pages registered indocs-site/src/sidebar.mjs.Foundation changes at the documentation level: primitive-scale + semantic-alias color model (light/dark-ready) with
stagekept as a VisionSet-specific token; brand separated from functional semantics (the exactly-two-sites/count rules removed); Geist Sans/Mono with semantic type roles; radius by material level (6/12/16/full); materials replacing generic shadow tiers; action hierarchy replacing the one-filled-button count (and the button-goes-green-for-save principle removed); a general async-feedback baseline replacing issue-specific timing history; Title Case for labels / sentence case for prose replacing sentence-case-everywhere; copy bans replaced by principles.No production file changed: nothing under
frontend/,src/, ortests/.Deliberate tensions, reported
frontend/ui-core/src/screens/*out of scope. The tests stay (they enforce the current, unchanged implementation); removing them belongs to the token/primitive implementation phase. Until then,tests/scripts/design_tokens.test.mjs's brand-site roster and the screen-level button-count tests enforce rulesDESIGN.mdno longer states — they pin the implementation, not the contract.feat/shadcn-foundation,feat/shadcn-primitives) describe the same target direction from the implementation side; sequencing them against this branch is a review decision.Found, not fixed
tests/scripts/favicon.test.mjsasserts hex#eb5a47as "the Robomous accent" while the brand token is#e85d44— pre-existing, out of scope here.docs/annotations.md's showcase section still describes v1-era demo styling (#d0d7deborders, "Robomous orange as accent"); it describes the demo page and predates this change.Test plan
All checks ran inside Linux Docker (
visionset-gate:latest, which clones the committed branch from the repo mounted read-only, so line endings materialize as in CI):pnpm test:scripts→ 107 pass / 0 fail (includesdocs_links,docs_sidebar,design_tokens).bash scripts/check.sh docs→ PASSED (site build, deterministic projection, 4260 internal links across 47 pages resolve).Browser and python suites are untouched by this diff; CI runs the exhaustive matrix.
#706 and the shadcn branches are untouched.