Echelon Design System

Shared design-system infrastructure for Echelon Foundry applications.

This repository is governed by the Echelon engineering capability stack:

• State-Directed Engineering / Ordo
• Repository Operating System (ROS)
• Visual Engineering
• Communication Engineering

The design system will provide shared visual foundations, reusable browser-native components, application patterns, accessibility contracts, behavioral state models where warranted, and integration points for Echelon applications.

Repository requirements and implementation work should be captured through ROS and shaped by Ordo rather than treating the component catalog as the source of domain truth.

Current capability baseline:

• SDE / Ordo 1.3.0
• ROS 3.1.4
• Visual Engineering 1.0.0
• Communication Engineering 1.0.0

Forma

Forma is the product name for this Echelon Foundry design system. The package identifier is @echelon-foundry/design-system. Forma 0.1.0 is the first application-consumption baseline.

Forma is intentionally zero-runtime. Semantic HTML, CSS, design tokens, accessibility contracts, and visual patterns live here. Behavior beyond browser-native interaction belongs to the consuming application, normally through Limen.

Build the component documentation site with:

npm run site:check

The generated GitHub Pages artifact is written to site-dist/. The site is generated from the component catalog: canonical markup in patterns/, one documentation entry per component in catalog/components/, and CSS hooks derived from the built stylesheet. Every component page has the same sections (purpose, live examples with copyable HTML, a mobile example in a real narrow viewport, API, states, accessibility, responsive behavior, motion, usage guidance and related components). See docs/CATALOG-AUTHORING.md to document a component and docs/COMPONENT-INVENTORY.md for the full inventory, planned components and known issues. Agent usage rules are in docs/AGENT-USAGE.md.

Public component examples use readable inert <ef-*> authoring tags around the canonical native HTML:

<ef-switch class="ef-component-tag">
  <label class="ef-switch">
    <input class="ef-switch__input" type="checkbox" role="switch">
    <span class="ef-switch__track" aria-hidden="true"></span>
    <span class="ef-switch__text">
      <span class="ef-switch__label">Notifications</span>
    </span>
  </label>
</ef-switch>

The wrapper is not registered with customElements.define(); Forma remains zero-runtime and the native HTML inside the tag owns semantics and interaction.

Application consumption

Applications must consume a pinned Forma release rather than copying CSS or tracking the repository branch. See docs/CONSUMING-FORMA.md for the canonical dependency, ownership boundaries, mobile rules, and upgrade procedure.

A version tag builds and validates the exact package archive, exercises it in a clean consumer, and attaches the tarball to the GitHub release. npm publishing may be enabled through Trusted Publishing without changing the application contract.

Marketing sites

Forma is the shared presentation system for every Echelon marketing website. The Echelon Foundry site is the visual reference, and each site consumes the same pinned artifacts:

• the MarketingShell;
• the brand-neutral marketing components and layouts;
• the Echelon Marketing Theme.

Start with docs/MARKETING-SITES.md and the reference fixture in examples/echelon-marketing-site.

Branding and skins

Forma supports versioned, scoped white-label presentation through Brand Manifests and zero-runtime skin presets. Brand manifests compile to static CSS custom-property scopes; applications retain runtime selection/persistence and domain authority.

See docs/BRANDING.md and requirements/WHITE-LABEL-AND-SKINNING.md.

Aegis fault presentation

Forma includes a zero-runtime fault presentation family for Aegis Presentation.T: inline, notification, banner, blocking, summary, recovery actions, references, safe details, and diagnostic persistence status.

Applications should map Aegis through the safe presentation model rather than bind a raw Fault. Recovery actions remain application/Ordo authorized and Limen-executed.

See docs/AEGIS-INTEGRATION.md and requirements/AEGIS-FAULT-PRESENTATION.md.

Object metadata and diagram/workflow presentation

Forma now explicitly treats descriptive object metadata and diagram/workflow presentation as reusable cross-cutting capabilities.

Objects may carry consumer-supplied metadata such as identifiers, descriptions, tags, owner/role, phase/category, status text, provenance/source references, and custom namespaced fields. Forma may present selected metadata, but the consuming application/profile remains the authority for values and meaning.

Workflow/diagram items may also carry authored fill, border/stroke, accent, connector, and safe foreground colors. Color is presentation only. Semantic workflow type/status never derives from color, and meaningful distinctions must survive forced colors, grayscale, and backgrounds-disabled output.

See requirements/OBJECT-METADATA-AND-DIAGRAM-PRESENTATION.md.

Portable workflows

Forma owns the portable workflow standard (.forma-workflow.json): a versioned JSON Schema, independent validation, deterministic layout, static HTML rendering, and the embeddable <forma-workflow> renderer and editor. None of it needs Forma Studio.

Need	Use
The format	docs/workflow/FORMAT.md, schema schemas/workflow/1.0/forma-workflow.schema.json
Validate in CI or from an agent	forma-workflow validate --json (docs/workflow/VALIDATION.md)
Static or complete-document HTML	forma-workflow render (docs/workflow/RENDERING.md)
Embed a viewer or editor	@echelon-foundry/forma-workflow (docs/workflow/EMBEDDING.md, examples/workflow-embedding)
Produce workflows elsewhere	docs/workflow/EXTERNAL-PRODUCERS.md
Reference fixtures	examples/workflows/

The design-system package stays zero-runtime. The editor ships separately; see ADR-0006. Run npm run workflow:check for the full workflow test suite.

Figma

Forma treats Figma as a design and developer-consumption surface, not as a second source of truth. Canonical tokens remain in tokens/echelon.tokens.json, canonical component anatomy remains in patterns/*.html, and figma/component-contracts.json provides complete, machine-readable coverage for the Figma library.

See docs/FIGMA.md for the variable, component, and Code Connect workflow. The public package also exposes ./tokens.json and ./figma/components.json for design tooling.

License

Source available under PolyForm Noncommercial 1.0.0 for permitted noncommercial uses. Commercial use requires a separate license from Echelon Foundry. Previously distributed versions remain subject to the licenses under which they were released.

Commercial licensing information is forthcoming.