Marvia

Sign inSign up

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.

  1. 01Design tokenIs this a value — color, space, radius, shadow, type?@marvia/ui/tokens
  2. 02PrimitiveIs this a single interactive or display element?@marvia/ui/primitives
  3. 03CompoundIs this a small composition of primitives with one job?@marvia/ui/compound
  4. 04BlockIs this a page-level region made of compounds?@marvia/ui/blocks
  5. 05PatternIs this the shape of a whole page?@marvia/patterns
  6. 06SchemaCan the page be described as data instead of code?@marvia/schemas
  7. 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.

Page headerToolbarMetric gridWidget gridActivity
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.

Thread listMessage streamPersistent prompt input
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.

OverviewMetricsVisual cardsIssuesRecommendationsAI summaryActionsHistory
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.

Section navForm sectionsSave barDanger zone
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.

HeroCategory filtersExtension gridDetail drawer
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.

Track headerLesson listLesson bodyNext 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.

BalanceUsage chartTransactionsPlan
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.

IdentityPreferencesSessions
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.

List paneDetail pane
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.

ToolbarTableRow actionsEditor drawer
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.

HeaderSearch and filtersListPagination
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.

HeaderPrimary contentMetadata sidebarRelated
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.

Query barFacetsResultsEmpty state
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.

FiltersGrouped eventsLoad more
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.

Range pickerHeadline metricsChartsBreakdown table
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.

SelectorsAligned metric rowsDelta summary
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.

ToolbarColumn headersRowsBulk barPagination
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.

Step railStep contentFooter navigation
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.

Brand panelProvider buttonsLegal note
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.

Change listDiffComment thread
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.

Request summaryPolicyDecision actionsAudit trail
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.

Source pickerMappingPreviewCommit
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.

ScopeFormatOptionsResult
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.

WelcomeWorkspace setupFirst analysisDone
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.

Table of contentsArticleOn-this-page
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.

EditorPreviewStatus bar
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.

InputGrouped resultsFooter hints
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.

Selection headerProperty groupsActions
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.

HeaderBodyFooter actions
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.

TitleBodyActions
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.

Panel headerContext bodyPrompt
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.

CodeExplanationRecovery actions
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.

Illustration or iconExplanationPrimary action
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.

Skeleton headerSkeleton body
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.

Workspace summaryInsightsRecent activity

actions: Refresh, Analyze URL (1 cr)

access: guest · member · admin · owner

report.schema

pattern: report

A snapshot rendered in the fixed report order.

OverviewMetricsVisual CardsIssuesRecommendationsAI SummaryActionsHistory

actions: Refresh report (1 cr), Export

access: guest · member · admin · owner

content.schema

pattern: content

One editor and one renderer for every content type.

DocumentMetadata

actions: Save draft, Publish

access: member · admin · owner

settings.schema

pattern: settings

Standardised configuration surface.

GeneralMembersBillingIntegrationsNotificationsAdvancedDanger Zone

actions: Save changes

access: admin · owner

workspace.schema

pattern: detail

Identity, members and usage of a single workspace.

IdentityUsageMembers

actions: Invite member

access: member · admin · owner

table.schema

pattern: table

Dense tabular data with sorting and selection.

Rows

actions: Filter, Bulk action

access: guest · member · admin · owner

list.schema

pattern: list

Browsable collection with search and filters.

Items

actions: Search, Create

access: guest · member · admin · owner

form.schema

pattern: settings

Generated form with validation and conditional fields.

Fields

actions: Submit

access: member · admin · owner

marketplace.schema

pattern: marketplace

Discover, preview and install extensions.

FeaturedCatalog

actions: Install

access: guest · member · admin · owner

learning.schema

pattern: learning

Teach, then link the lesson to an action.

TrackLesson

actions: Start lesson

access: guest · member · admin · owner

documentation.schema

pattern: documentation

Reference material in a stable reading column.

Article

actions: Search docs

access: guest · member · admin · owner

wizard.schema

pattern: wizard

A multi-step task with no dead ends.

Steps

actions: Continue

access: member · admin · owner

chat.schema

pattern: chat

Prompt-first conversation bound to workspace context.

ThreadPrompt

actions: Send prompt (1 cr)

access: member · admin · owner

analytics.schema

pattern: analytics

Explain a trend across a chosen range.

HeadlineTrendsBreakdown

actions: Change range, Refresh (1 cr)

access: member · admin · owner

comparison.schema

pattern: comparison

Two snapshots aligned metric by metric.

SelectionDeltasDetail

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

1. Overview2. Metrics3. Visual Cards4. Issues5. Recommendations6. AI Summary7. Actions8. History

Settings schema

GeneralMembersBillingIntegrationsNotificationsAdvancedDanger Zone

Content types

blogdocsguidetutorialfaqplaybookacademyknowledgerelease-notesannouncement

Form fields

texttextareanumberemailurlselectmultiselectcheckboxswitchradiodatesecret

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

  1. 1Can this be an extension?
  2. 2Can this reuse a pattern?
  3. 3Can this reuse a schema?
  4. 4Can this reuse an existing block?
  5. 5Can this reuse existing tokens?

Coding rules

  • Reuse before createComponents, layouts, patterns, schemas and tokens are reused, never re-derived.
  • No duplicationNever duplicate CSS, pages, forms or report layouts.
  • No feature primitivesA feature never introduces its own Button, Card or Field.
  • Predictable namingDescriptive PascalCase names such as MetricCard or WorkspaceSwitcher; no vague nouns.
  • Small modulesOne responsibility per file, no hidden logic, no magic.