marvia-04
34 patterns, 15 schemas
The constitution as code. Patterns are the only page blueprints, schemas are the only page descriptions, and the selection flow decides which layer answers a need. Everything on this page is read from the kernel packages, so documentation cannot drift from implementation.
Pattern library
34 blueprints
packages/patterns
Schema library
15 schemas
packages/schemas
Selection flow
7 levels
never skip a level
Architecture gate
5 questions
any yes means reuse
component selection
Seven levels, in order
Every UI decision starts at level one and stops at the first level that answers the need. Skipping a level is how design systems die.
- 01Design tokenIs this a value — color, space, radius, shadow, type?@marvia/ui/tokens
- 02PrimitiveIs this a single interactive or display element?@marvia/ui/primitives
- 03CompoundIs this a small composition of primitives with one job?@marvia/ui/compound
- 04BlockIs this a page-level region made of compounds?@marvia/ui/blocks
- 05PatternIs this the shape of a whole page?@marvia/patterns
- 06SchemaCan the page be described as data instead of code?@marvia/schemas
- 07PageOnly now: render the schema inside the pattern.src/routes
pattern library
Page blueprints
A pattern declares purpose, layout, actions, blocks, responsive behaviour, accessibility rules, shortcuts and the components it may and may not use. A page outside this library is a defect.
surface
Dashboard
dashboard-layout
Answer 'what is the state of my workspace?' at a glance.
- Primary
- Run analysis
- Blocks
- stat-grid, data-panel, activity-timeline
- Responsive
- Widgets stack to one column below md; metric grid 2-up on sm.
- A11y
- Widgets are list items with accessible names · Refresh announces completion via live region
- Keys
- g d — go to dashboard · r — refresh
- Forbidden
- Bespoke grids · Realtime tickers
Chat
split-layout
Prompt-first conversation attached to a workspace object.
- Primary
- Send prompt
- Blocks
- prompt-input, markdown-content
- Responsive
- Thread list collapses into a drawer below lg.
- A11y
- Stream is an aria-live polite log · Prompt keeps focus after send
- Keys
- / — focus prompt · cmd+enter — send
- Forbidden
- Autoplaying audio · Second prompt component
Report
report-layout
Present a snapshot as a fixed, comparable structure.
- Primary
- Refresh report
- Blocks
- stat-grid, issue-card, recommendation-card, chart-container
- Responsive
- Sections are full width; metric grids reflow 4→2→1.
- A11y
- Every section is a landmark with aria-label · Severity is text, never color alone
- Keys
- r — refresh · e — export
- Forbidden
- Reordered sections · Extension-supplied layouts
Settings
split-layout
Change workspace or account configuration safely.
- Primary
- Save changes
- Blocks
- form-shell, field, confirmation-dialog
- Responsive
- Section nav becomes a top tab row below lg.
- A11y
- Unsaved changes warned before navigation · Danger actions require typed confirmation
- Keys
- cmd+s — save
- Forbidden
- Auto-saving destructive fields
Marketplace
dashboard-layout
Discover and install extensions.
- Primary
- Install extension
- Blocks
- feature-grid, data-panel, confirmation-dialog
- Responsive
- Grid 3→2→1 columns.
- A11y
- Install states announced · Permissions listed before install
- Keys
- / — search
- Forbidden
- Install without a permission summary
Learning
documentation-layout
Teach a concept, then link it to an action.
- Primary
- Start lesson
- Blocks
- markdown-content, feature-grid
- Responsive
- Lesson list collapses above content on mobile.
- A11y
- Reading order matches visual order
- Keys
- n — next lesson
- Forbidden
- Bespoke lesson renderers
Billing
dashboard-layout
Show credits, spend and plan without surprise.
- Primary
- Buy credits
- Blocks
- stat-grid, chart-container, data-panel
- Responsive
- Chart full width above the table on mobile.
- A11y
- Currency and credit values readable by screen readers
- Keys
- b — buy credits
- Forbidden
- Time-based charges
Profile
split-layout
Manage personal identity and preferences.
- Primary
- Save profile
- Blocks
- form-shell, field
- Responsive
- Single column below lg.
- A11y
- Avatar has meaningful alt text
- Keys
- cmd+s — save
- Forbidden
- Role editing outside Members
Split View
split-layout
Keep a list and its detail visible together.
- Primary
- Open item
- Blocks
- data-panel
- Responsive
- Detail replaces the list below lg.
- A11y
- Panes are labelled regions
- Keys
- j/k — move selection
- Forbidden
- Three or more panes
data
CRUD
dashboard-layout
Create, read, update and delete one resource type.
- Primary
- Create record
- Blocks
- data-panel, form-shell, confirmation-dialog
- Responsive
- Table becomes a card list below md.
- A11y
- Row actions reachable by keyboard · Delete always confirmed
- Keys
- c — create · del — delete
- Forbidden
- Inline delete without confirmation
List
dashboard-layout
Browse many items of one kind with filters.
- Primary
- Open item
- Blocks
- data-panel, search-box, empty-state
- Responsive
- Single column below md; filters collapse into a drawer.
- A11y
- List semantics with item count announced
- Keys
- / — search · j/k — move
- Forbidden
- Infinite scroll without a count
Detail
split-layout
Everything known about a single object.
- Primary
- Primary object action
- Blocks
- data-panel, activity-timeline
- Responsive
- Sidebar moves below content on lg and under.
- A11y
- Heading hierarchy starts at the object name
- Keys
- e — edit
- Forbidden
- Duplicate object title in two places
Search
dashboard-layout
Find anything in the workspace by text.
- Primary
- Open result
- Blocks
- search-box, empty-state
- Responsive
- Facets collapse into a drawer below md.
- A11y
- Result count announced on every query
- Keys
- / — focus search
- Forbidden
- Silent zero-result screens
Timeline
dashboard-layout
Show what happened, in order, with actors.
- Primary
- Filter events
- Blocks
- activity-timeline, empty-state
- Responsive
- Single column always; date headers stick.
- A11y
- Ordered list semantics with absolute timestamps
- Keys
- f — filter
- Forbidden
- Relative-only timestamps
Analytics
dashboard-layout
Explain a trend across a chosen range.
- Primary
- Change range
- Blocks
- stat-grid, chart-container, data-panel
- Responsive
- Charts stack; table scrolls horizontally.
- A11y
- Every chart has a text summary or data table
- Keys
- r — refresh
- Forbidden
- Charts without a text equivalent
Comparison
split-layout
Put two snapshots or entities side by side.
- Primary
- Compare
- Blocks
- stat-grid, data-panel
- Responsive
- Sides stack with sticky labels below lg.
- A11y
- Deltas expressed in text, not only arrows
- Keys
- s — swap
- Forbidden
- Color-only deltas
Table
dashboard-layout
Dense, sortable, selectable tabular data.
- Primary
- Bulk action
- Blocks
- data-panel, toolbar
- Responsive
- Horizontal scroll with a pinned first column.
- A11y
- Sortable headers expose aria-sort · Selection count announced
- Keys
- shift+click — range select
- Forbidden
- Nested tables
flow
Wizard
split-layout
Guide a multi-step task with no dead ends.
- Primary
- Continue
- Blocks
- form-shell, field
- Responsive
- Step rail becomes a progress bar on mobile.
- A11y
- Step changes announced · Errors summarised at the top of the step
- Keys
- enter — continue · esc — exit
- Forbidden
- Steps that cannot be revisited
Authentication
split-layout
Request identity at the gated action and preserve intent.
- Primary
- Continue with provider
- Blocks
- hero, form-shell
- Responsive
- Single column below md.
- A11y
- Provider buttons are real buttons with visible focus
- Keys
- enter — submit
- Forbidden
- Password fields for OAuth-only flows
Review
split-layout
Compare proposed changes before they land.
- Primary
- Approve
- Blocks
- data-panel, markdown-content
- Responsive
- Diff scrolls; list becomes a drawer.
- A11y
- Additions and removals labelled in text
- Keys
- a — approve
- Forbidden
- Approve without a diff
Approval
dashboard-layout
Record a decision with an accountable actor.
- Primary
- Approve
- Blocks
- data-panel, activity-timeline, confirmation-dialog
- Responsive
- Single column below md.
- A11y
- Decision result announced and persisted
- Keys
- a — approve · x — reject
- Forbidden
- Silent auto-approval
Import
split-layout
Bring external data in with a preview before commit.
- Primary
- Import
- Blocks
- form-shell, data-panel
- Responsive
- Mapping table scrolls horizontally.
- A11y
- Validation errors listed with row references
- Keys
- enter — next
- Forbidden
- Commit without preview
Export
split-layout
Take data out in a declared format.
- Primary
- Export
- Blocks
- form-shell
- Responsive
- Single column.
- A11y
- Download completion announced
- Keys
- e — export
- Forbidden
- Silent partial exports
Onboarding
split-layout
Reach first value in three clicks.
- Primary
- Start first analysis
- Blocks
- hero, form-shell
- Responsive
- Single column below lg.
- A11y
- Progress announced; skip always reachable
- Keys
- enter — continue
- Forbidden
- Mandatory tours
content
Documentation
documentation-layout
Reference material with a stable reading column.
- Primary
- Read
- Blocks
- markdown-content
- Responsive
- Both rails collapse below lg, article stays first.
- A11y
- Anchor links have discernible names
- Keys
- cmd+k — search docs
- Forbidden
- Second markdown renderer
Content
split-layout
Author and render any content type from one document schema.
- Primary
- Publish
- Blocks
- markdown-content, form-shell
- Responsive
- Editor and preview become tabs below lg.
- A11y
- Editor is a labelled textbox with save status announced
- Keys
- cmd+s — save · cmd+shift+p — publish
- Forbidden
- Per-type editors
overlay
Command
split-layout
Reach any action from anywhere in one keystroke.
- Primary
- Run command
- Blocks
- search-box
- Responsive
- Full-width sheet on mobile.
- A11y
- Combobox roles with active-descendant management
- Keys
- cmd+k — open · esc — close
- Forbidden
- Destructive commands without confirmation
Inspector
split-layout
Inspect and edit properties of a selection.
- Primary
- Apply
- Blocks
- form-shell, field
- Responsive
- Becomes a bottom sheet on mobile.
- A11y
- Focus moves to the inspector on open
- Keys
- esc — close
- Forbidden
- Hidden destructive actions
Drawer
split-layout
Do a side task without losing the page.
- Primary
- Confirm
- Blocks
- form-shell
- Responsive
- Full-height sheet on mobile.
- A11y
- Focus trapped, restored on close
- Keys
- esc — close
- Forbidden
- Nested drawers
Modal
split-layout
Interrupt only for a decision that cannot wait.
- Primary
- Confirm
- Blocks
- confirmation-dialog
- Responsive
- Full-width with 16px inset on mobile.
- A11y
- Dialog role, labelled title, focus trap
- Keys
- esc — cancel · enter — confirm
- Forbidden
- Multi-step content
Side Panel
split-layout
Persistent contextual help or AI assistance.
- Primary
- Ask
- Blocks
- prompt-input, markdown-content
- Responsive
- Collapses to an icon rail below lg.
- A11y
- Panel toggle exposes aria-expanded
- Keys
- cmd+/ — toggle
- Forbidden
- Blocking the main content
state
Error
split-layout
Explain a failure and offer the way back.
- Primary
- Retry
- Blocks
- error-state
- Responsive
- Centered column at every size.
- A11y
- Error is an alert with a focusable retry
- Keys
- r — retry
- Forbidden
- Stack traces in production
Empty State
split-layout
Turn emptiness into the next step.
- Primary
- Create first item
- Blocks
- empty-state
- Responsive
- Centered column at every size.
- A11y
- Action is a real button, not decorative text
- Keys
- c — create
- Forbidden
- Blank screens · Apologetic copy
Loading
split-layout
Hold the layout while data resolves.
- Primary
- None
- Blocks
- loading-state
- Responsive
- Skeletons mirror the final layout at every breakpoint.
- A11y
- aria-busy on the region, no focus stealing
- Keys
- esc — cancel
- Forbidden
- Spinners · Layout shift
schema library
Pages are data
Each schema names the pattern it renders into and declares header, toolbar, sections, widgets, permissions and its loading, empty and error states. Extensions supply data for sections; they never supply layouts.
dashboard.schema
pattern: dashboard
The state of the workspace in one screen.
actions: Refresh, Analyze URL (1 cr)
access: guest · member · admin · owner
report.schema
pattern: report
A snapshot rendered in the fixed report order.
actions: Refresh report (1 cr), Export
access: guest · member · admin · owner
content.schema
pattern: content
One editor and one renderer for every content type.
actions: Save draft, Publish
access: member · admin · owner
settings.schema
pattern: settings
Standardised configuration surface.
actions: Save changes
access: admin · owner
workspace.schema
pattern: detail
Identity, members and usage of a single workspace.
actions: Invite member
access: member · admin · owner
table.schema
pattern: table
Dense tabular data with sorting and selection.
actions: Filter, Bulk action
access: guest · member · admin · owner
list.schema
pattern: list
Browsable collection with search and filters.
actions: Search, Create
access: guest · member · admin · owner
form.schema
pattern: settings
Generated form with validation and conditional fields.
actions: Submit
access: member · admin · owner
marketplace.schema
pattern: marketplace
Discover, preview and install extensions.
actions: Install
access: guest · member · admin · owner
learning.schema
pattern: learning
Teach, then link the lesson to an action.
actions: Start lesson
access: guest · member · admin · owner
documentation.schema
pattern: documentation
Reference material in a stable reading column.
actions: Search docs
access: guest · member · admin · owner
wizard.schema
pattern: wizard
A multi-step task with no dead ends.
actions: Continue
access: member · admin · owner
chat.schema
pattern: chat
Prompt-first conversation bound to workspace context.
actions: Send prompt (1 cr)
access: member · admin · owner
analytics.schema
pattern: analytics
Explain a trend across a chosen range.
actions: Change range, Refresh (1 cr)
access: member · admin · owner
comparison.schema
pattern: comparison
Two snapshots aligned metric by metric.
actions: Compare (1 cr)
access: member · admin · owner
fixed structures
What extensions can never change
The report order, the settings tabs, the content types and the generated field set belong to the kernel.
Report schema
Settings schema
Content types
Form fields
ai coding rules
Rules for every contributor, human or agent
Before anything new is created, the architecture gate is answered. Any yes means reuse.
Architecture gate
- 1Can this be an extension?
- 2Can this reuse a pattern?
- 3Can this reuse a schema?
- 4Can this reuse an existing block?
- 5Can this reuse existing tokens?
Coding rules
- Reuse before create — Components, layouts, patterns, schemas and tokens are reused, never re-derived.
- No duplication — Never duplicate CSS, pages, forms or report layouts.
- No feature primitives — A feature never introduces its own Button, Card or Field.
- Predictable naming — Descriptive PascalCase names such as MetricCard or WorkspaceSwitcher; no vague nouns.
- Small modules — One responsibility per file, no hidden logic, no magic.