Skip to content

Commit 63a73d4

Browse files
Sayhi-bzbSayhi-bzb
committed
refactor: add runtime surface validation, update gallery styles, add design docs
First, add runtime manifest reading and surface assertion checks to artifact workflow to validate runtime drift. Then update gallery shell CSS to apply consistent block spacing for agent components across both preview and runtime documents, and add a test for this spacing behavior. Finally add comprehensive design system documentation files and expand existing design spec, plus add new test case for runtime verification when host glue code changes.
1 parent 7f258f0 commit 63a73d4

12 files changed

Lines changed: 1434 additions & 235 deletions

File tree

‎apps/agent-html/DESIGN.md‎

Lines changed: 59 additions & 233 deletions
Large diffs are not rendered by default.

‎apps/agent-html/design/README.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Design Standards
2+
3+
This directory contains the working frontend design standards for the `agent-html` app.
4+
5+
## Ownership
6+
7+
This package owns the implementation-facing design rules for the app frontend.
8+
It does not own the high-level visual philosophy, which remains in [`../DESIGN.md`](../DESIGN.md).
9+
10+
## Reading Order
11+
12+
1. [`../DESIGN.md`](../DESIGN.md) for visual philosophy and product feel
13+
2. [`constitution.md`](./constitution.md) for global design-system law
14+
3. [`tokens.md`](./tokens.md) for token layers, naming, and consumption
15+
4. [`typography.md`](./typography.md) for text roles and hierarchy
16+
5. [`layout.md`](./layout.md) for shell, spacing, and responsive structure
17+
6. [`components.md`](./components.md) for component-family standards
18+
7. [`code-structure.md`](./code-structure.md) for implementation boundaries and review rules
19+
20+
## Which Document Answers What
21+
22+
- If the question is "what should this product feel like," read `../DESIGN.md`.
23+
- If the question is "what is globally allowed or forbidden," read `constitution.md`.
24+
- If the question is "where does this visual value come from," read `tokens.md`.
25+
- If the question is "what text role should this use," read `typography.md`.
26+
- If the question is "how should this page be structured," read `layout.md`.
27+
- If the question is "how should this component family behave," read `components.md`.
28+
- If the question is "where should this code live," read `code-structure.md`.
29+
30+
## Boundary Rule
31+
32+
Each file in this directory should answer one class of question.
33+
If a rule is fully specified in one file, other files should link to it rather than restate it.

‎apps/agent-html/design/code-structure.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# UI Code Structure Specification
2+
3+
## Purpose
4+
5+
This document defines how frontend design decisions map onto code structure.
6+
It exists so the design system remains enforceable in implementation.
7+
8+
## Ownership
9+
10+
This document owns directory responsibilities, class-usage rules, variant management, promotion
11+
rules, and review anti-patterns.
12+
It does not define visual philosophy, typography roles, or component-family appearance rules.
13+
14+
## Directory Roles
15+
16+
### `src/index.css`
17+
18+
This file is the token and theme-mapping entrypoint.
19+
20+
It owns:
21+
22+
- font setup
23+
- semantic CSS variables
24+
- light and dark theme mappings
25+
- shared base-layer application rules
26+
27+
It MUST NOT become a dumping ground for page-specific styles.
28+
29+
### `src/components/ui/*`
30+
31+
This directory is the primitive UI layer.
32+
33+
It owns:
34+
35+
- shadcn-derived primitives
36+
- primitive variants
37+
- primitive slot styling
38+
- shared interaction surfaces
39+
40+
### `src/components/*`
41+
42+
This directory is the composite UI layer.
43+
44+
It owns:
45+
46+
- shell components
47+
- navigation modules
48+
- reusable feature-facing composition
49+
- stable product patterns built from primitives
50+
51+
It MUST NOT become a second primitive library.
52+
53+
### Page / App Layer
54+
55+
The page layer owns:
56+
57+
- data shaping
58+
- page-specific composition
59+
- local content ordering
60+
- temporary view structure before a pattern proves reusable
61+
62+
It MUST NOT define new system-wide visual truth.
63+
64+
## Styling Source of Truth
65+
66+
Design decisions should originate from this order:
67+
68+
1. token and theme mapping
69+
2. primitive variants and slots
70+
3. composites built from primitives
71+
4. page-level composition
72+
73+
If a page needs repeated local visual overrides, the rule probably belongs higher in the system.
74+
75+
## Class Usage Rules
76+
77+
Tailwind utility usage is allowed, but it MUST remain system-led.
78+
79+
- prefer semantic token-backed utilities
80+
- prefer existing primitive variants before adding local overrides
81+
- prefer composition over local restyling
82+
- use arbitrary values sparingly and only when no sanctioned token or constant exists
83+
- avoid repeating the same utility bundle across multiple files when it should become a primitive
84+
or composite concern
85+
86+
## Variant Management
87+
88+
Variants belong to primitives first.
89+
90+
- if multiple screens need the same interaction surface in different visual forms, add or refine a
91+
primitive variant
92+
- if the pattern is a reusable arrangement of primitives, create a composite
93+
- if the pattern is unique to one screen, keep it local until reuse is proven
94+
95+
## Layout Constant Management
96+
97+
Structural constants such as shell heights and widths MUST be centralized.
98+
99+
- layout constants SHOULD be declared close to the shell primitive that owns them
100+
- page code MUST NOT redefine shell structure constants ad hoc
101+
- if a structural value becomes reused beyond one shell context, evaluate whether it should be
102+
promoted into a more explicit system constant
103+
104+
## Primitive Change Policy
105+
106+
When editing a primitive:
107+
108+
- assume the blast radius is global
109+
- evaluate downstream consumers
110+
- prefer additive variants over breaking stylistic rewrites
111+
- preserve accessibility and interaction semantics
112+
113+
## Composite Promotion Policy
114+
115+
A page-level UI block should be promoted to a composite when:
116+
117+
- it appears on multiple screens
118+
- it encodes a stable interaction pattern
119+
- it would otherwise duplicate layout or state logic
120+
121+
It should stay local when:
122+
123+
- it is a one-off placeholder
124+
- it is purely contextual
125+
- its reuse model is still unclear
126+
127+
## Review Checklist
128+
129+
A UI review should verify:
130+
131+
- no raw visual values bypass the token model
132+
- no new parallel primitive was created
133+
- no page is styling around primitives when a variant should exist
134+
- no composite is leaking page-specific assumptions into the system
135+
- no shell constants are copied into random files
136+
- no accessibility behavior was lost during visual customization
137+
138+
## Anti-Patterns
139+
140+
The following should be rejected by default:
141+
142+
- duplicating button or input behavior outside `src/components/ui/*`
143+
- creating a second sidebar implementation with custom markup
144+
- hard-coding colors in feature components
145+
- encoding typography decisions ad hoc in every page
146+
- growing page-local utility bundles into a shadow design system

‎apps/agent-html/design/components.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# Component Specification
2+
3+
## Purpose
4+
5+
This document standardizes the component language for the workspace shell.
6+
It defines the expectations for major component families used across the app.
7+
8+
## Ownership
9+
10+
This document owns component-family standards and reuse expectations.
11+
It does not define token flow, primitive-layer governance, or code-placement rules; those belong to
12+
`constitution.md` and `code-structure.md`.
13+
14+
## Component Philosophy
15+
16+
Components in this app should remain:
17+
18+
- compact
19+
- neutral
20+
- task-oriented
21+
- accessible
22+
- predictable
23+
24+
They are not decorative objects.
25+
They exist to support fast scanning and stable interaction.
26+
27+
## Button Standard
28+
29+
Buttons are compact utility controls.
30+
31+
Characteristics:
32+
33+
- compact height
34+
- medium-emphasis typography
35+
- rounded rectangle geometry
36+
- clear primary, outline, ghost, and destructive distinction
37+
- visible focus ring
38+
39+
Usage rules:
40+
41+
- `default` is the primary action button
42+
- `outline` is the standard secondary action
43+
- `ghost` is for shell chrome and low-emphasis controls
44+
- `destructive` is reserved for risky actions
45+
- `link` is for inline textual action only
46+
47+
Larger sizes should remain restrained and MUST NOT introduce marketing-button behavior.
48+
49+
## Input Standard
50+
51+
Inputs are short, dense, and neutral.
52+
53+
Characteristics:
54+
55+
- compact height
56+
- rounded rectangle shape
57+
- border-led definition
58+
- restrained background treatment
59+
- clear focus-visible and invalid states
60+
61+
Rules:
62+
63+
- input styling MUST remain quiet relative to surrounding layout
64+
- invalid state MUST use the shared destructive and ring system
65+
- placeholder styling MUST remain secondary
66+
67+
## Card and Panel Standard
68+
69+
Cards are the default content container.
70+
71+
Characteristics:
72+
73+
- surface from `card`
74+
- text from `card-foreground`
75+
- thin border
76+
- medium radius
77+
- optional light shadow
78+
- compact internal spacing
79+
80+
Rules:
81+
82+
- cards SHOULD carry sections, data, or activity groupings
83+
- cards MUST NOT depend on heavy branding or decorative gradients
84+
- dashed internal blocks MAY be used for placeholders or segmentation only
85+
86+
## Sidebar Standard
87+
88+
The sidebar is a first-class component family.
89+
90+
Characteristics:
91+
92+
- group-based navigation
93+
- compact item heights
94+
- icon-plus-label rows
95+
- muted labels
96+
- subtle hover and active states
97+
- collapsible desktop behavior
98+
- mobile sheet fallback
99+
100+
Rules:
101+
102+
- new navigation patterns SHOULD extend the sidebar family before creating a parallel system
103+
- active states SHOULD remain subtle and neutral-first
104+
- accent usage SHOULD stay scoped to orientation and navigation identity
105+
106+
## Menu and Overlay Standard
107+
108+
Dropdowns, sheets, and tooltips extend the same shell language.
109+
110+
Rules:
111+
112+
- overlays MUST use the same radius family as core surfaces
113+
- dropdown items MUST stay compact and scan-friendly
114+
- tooltip styling SHOULD remain functional and minimal
115+
- sheets SHOULD feel like shell extensions, not separate canvases
116+
117+
## Avatar and Identity Standard
118+
119+
Identity surfaces are supportive, not dominant.
120+
121+
Rules:
122+
123+
- avatars SHOULD stay compact
124+
- avatar framing SHOULD remain subtle
125+
- identity rows MAY combine avatar, primary label, and supporting line
126+
- identity components MUST NOT overpower navigation or task content
127+
128+
## Component State Rules
129+
130+
Relevant components must account for:
131+
132+
- default
133+
- hover
134+
- active
135+
- focus-visible
136+
- disabled
137+
- invalid where applicable
138+
- selected / expanded / open where applicable
139+
140+
State treatment MUST be coherent across families.
141+
142+
## Reuse Pipeline
143+
144+
The following page patterns should be promoted into explicit reusable composites once they recur:
145+
146+
- dashboard stat card
147+
- section header row
148+
- activity list item
149+
- empty state block
150+
- settings form section
151+
- list toolbar

0 commit comments

Comments
 (0)