A portable, multi-brand, web-platform-first design system: CSS-first, semantic-HTML-first, framework-agnostic, and independently versioned.
Status: experimental. There is no released CSS and no
public-stablesurface yet. The first CSS entrypoint exists as apublic-previewsurface.
The Design System is a standalone product intended to become open source and to be consumed through published artifacts rather than source reach-through.
Its first implementation horizon is frontend-focused:
- portable CSS with an explicit cascade/layer contract;
- semantic and classless base styling before specialized hooks;
- reference and semantic tokens with consumer-owned theme overrides;
- base primitives and semantic UI primitives kept distinct;
- bounded fluid spacing/type and container-first reusable-module responsiveness;
- native HTML/CSS interaction before shared JavaScript where compatibility and accessibility evidence permits it.
Rust and Cargo are the contributor-workspace and validation substrate. Consuming released frontend CSS will not require Rust or Cargo.
The repository currently provides:
- a Rust 2024 / resolver-3 Cargo workspace pinned to Rust 1.98.1;
- one contributor tool,
ds-check, for source-boundary, CSS layer-contract, token-authority, theme-contract, classless-base validation, and deterministic stylesheet measurement; - the first portable CSS entrypoint,
core.cssatpackages/styles/index.css(public-preview), which publishes the shared cascade layer order; seedocs/architecture/css-entrypoint.md; - the design-token authority imported by that entrypoint into
ds.tokens: internal reference values andpublic-previewsemantic roles, classified per property intokens.tsv; seedocs/architecture/tokens.md; - the theme contract in the same layer: the default follows the user's
light/dark preference, and
data-ds-scheme="light"or"dark"on<html>selects one explicitly, classified intheme.tsv; seedocs/architecture/theme.md; - the classless semantic base in
ds.base: zero-specificity defaults for ordinary HTML documents, text, links, tables, forms, disclosure, and dialogs, bound to the semantic roles, with owned subjects and exclusions classified inbase.tsv; seedocs/architecture/base.md; - the layout primitives in
ds.layouts: opt-in stack, cluster, and intrinsic grid layouts behind the.ds-stack,.ds-cluster, and.ds-gridclass hooks, with no breakpoint and no visual reordering, classified inlayouts.tsv; page shells stay consumer-owned; seedocs/architecture/layouts.md; - the primitives in
ds.primitives: the.ds-surfacebase primitive, which composes with any layout, and the.ds-actionUI primitive for native buttons and links, with primary, quiet, and icon variants and native or ARIA state only, classified inprimitives.tsv; seedocs/architecture/primitives.md; - one public hook vocabulary: the layout and primitive classes plus the
data-ds-schemetheme attribute, each styling only the element that carries it (a layout also reaches its direct children), with no@scopeand every otherdata-*name reserved; seedocs/architecture/hooks.md; - a brand theme fixture that maps one fictional consumer brand into the public semantic roles;
- a plain HTML consumer fixture that loads only that export and exercises every owned base default, a layouts fixture that uses the layouts inside a consumer-owned page shell, a primitives fixture that exercises every primitive hook and state, and a scoping fixture that checks each hook's reach against nested and lookalike markup;
- browser contract tests in Chromium, Firefox, and WebKit under
tests/browser/; - explicit compatibility classification in
bootstrap-surfaces.tsv; - an optional
public-previewTailwind v4 adapter that maps the same public semantic roles through@theme inline, has no Preflight, and keeps provider tooling isolated underadapters/tailwind/; - least-privilege GitHub Actions quality checks.
Components and utilities are not defined yet; their layers stay empty until a reviewed source change defines their contracts.
- Architecture explains the CSS entrypoint, cascade, tokens, theme, base styles, layouts, primitives, and public hooks.
- Styles source maps those contracts to files.
- Examples and fixtures show framework-free integration and the cases enforced by contributor checks.
- Browser tests describe the cross-engine assurance suite.
- Contributor tooling documents the repository-local checks.
From the repository root:
cargo fmt --all --check
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
cargo test --workspace --all-features --locked
cargo +1.98.1 check --workspace --all-targets --locked
cargo run --locked -p design-system-check -- audit packages/styles
cargo run --locked -p design-system-check -- check \
bootstrap-surfaces.tsv fixtures/plain-html
cargo run --locked -p design-system-check -- layers \
exports.tsv bootstrap-surfaces.tsv fixtures/plain-html
cargo run --locked -p design-system-check -- tokens \
tokens.tsv exports.tsv docs/architecture/tokens.md \
fixtures/plain-html fixtures/brand-theme fixtures/layouts fixtures/primitives \
fixtures/scoping tests/browser/probes
cargo run --locked -p design-system-check -- theme \
theme.tsv exports.tsv docs/architecture/theme.md \
fixtures tests/browser/probes
cargo run --locked -p design-system-check -- base \
base.tsv exports.tsv docs/architecture/base.md fixtures/plain-html
cargo run --locked -p design-system-check -- layout \
layouts.tsv exports.tsv docs/architecture/layouts.md fixtures/layouts
cargo run --locked -p design-system-check -- primitive \
primitives.tsv layouts.tsv exports.tsv docs/architecture/primitives.md \
fixtures/primitives
cargo run --locked -p design-system-check -- hooks \
layouts.tsv primitives.tsv theme.tsv exports.tsv docs/architecture/hooks.md \
fixtures/scoping
(cd adapters/tailwind && npm ci --no-audit --no-fund && npm run build)
cargo run --locked -p design-system-check -- tailwind \
adapters/tailwind/projection.tsv tokens.tsv adapter-exports.tsv \
bootstrap-surfaces.tsv adapters/tailwind adapters/tailwind/fixture/output.css
(cd tests/browser && npm ci && npx playwright install chromium firefox webkit && npx playwright test)The browser tests are contributor tooling. Consuming the CSS never requires Node, Rust, or Cargo.
See CONTRIBUTING.md for the contributor workflow and SECURITY.md for vulnerability reporting.
Repository paths are not API by default.
| Class | Meaning |
|---|---|
public-stable |
Supported compatibility surface. None exists yet. |
public-preview |
Deliberately exposed but still moving. Currently the core.css entrypoint, its layer order, the semantic token roles in tokens.tsv, the theme default and data-ds-scheme hook in theme.tsv, the classless base defaults in base.tsv, the layout hooks in layouts.tsv, and the primitive hooks and states in primitives.tsv, together forming the hook vocabulary in docs/architecture/hooks.md. |
internal |
Not API; may change or disappear. Every other path uses this class. |
Product maturity and compatibility classification are separate. Experimental project maturity does not make an internal path public.
- Not a component framework for React, Solid, Vue, or another UI runtime.
- Not a Tailwind plugin. Tailwind may later exist as an optional adapter.
- Not a backend/service framework.
- Not a general-purpose UI kit copied from one consumer.
- Not yet a released CSS package or release artifact.
This repository is currently unlicensed. It is public and readable, but default copyright applies: public visibility is not permission to copy, modify, or redistribute the source.
Open-source licensing is intended but deliberately deferred until before the
first supported release candidate. No LICENSE file exists yet.