Concepts

Concepts and ownership

j3w1/theme is both a canonical design specification and the source of an official reusable web implementation. Understanding those roles keeps an application integration consistent.

What each layer owns

Layer	Responsibility
tokens/	Exact design values and aliases
spec/	Meaning, permitted uses, states, keyboard behavior and accessibility rules
exports/ and agents/	Generated machine contracts and consumption protocol
packages/ui	Official web implementation, types, styles and copy bundles
Portal and Vue demo	Human documentation and first-party package usage
Port mappings	Supported host keys for a particular native application
Execution evidence	What ran against which artifact, with environment and limits
Your application	Domain behavior, data, persistence, backend and authorization

The wiki and screenshots explain these layers; they do not replace the pinned sources. If package rendering contradicts the specification, that is a defect to investigate, not another palette to choose.

Primitives, roles and aliases

A primitive is a raw palette value. Consumers use semantic roles, which specify the job a value performs. For example, color.interaction.focus.ring is for focus; a text role with the same value is not interchangeable with it.

Aliases link roles to values; the resolved export follows those links for you. CSS names replace dots with dashes and add --: color.surface.canvas becomes --color-surface-canvas. Do not derive values from screenshots or use a primitive just because its appearance is close.

Profiles and eligibility

Profile	Status	Consumer use
default	Approved	Everyday True Black / Rose composition
heritage-ansi	Heritage	Historical study; not new approved UI mappings
extended	Proposed	Preview-only; blocked for delivery

A role's source status and consumption eligibility are different fields. Read the resolved token's eligibility:

• use: consume within the role's documented scope.
• use-and-report: use the pinned value in the approved default profile and disclose its pending decision IDs, including alias dependencies.
• A blocked action: do not consume it or invent a replacement.

A release number does not approve proposed profiles or pending roles. Consult the decision log and resolved export instead of assuming a status from a color's appearance.

Components, variants and states

All 67 inventory entries have official implementations in v1.1.0. Each has a canonical contract and maintained examples. A variant changes a supported form of the component; a state describes behavior such as disabled, invalid or selected. A state matrix demonstrates rendering; it does not prove every combination was exercised in a real application.

The package uses light DOM Custom Elements with native children. Markup, labels and ARIA relationships are deliberate composition surfaces. APIs differ by component; consult the generated contract rather than guessing props.

Pins, hashes and two kinds of lock

A release tag or full commit identifies the source revision. Resolve annotated tags to their commit, not the tag-object ID. A file digest identifies the bytes consumed. Read all contracts from one revision.

The package-manager lock records the runtime dependency. theme.lock.json records canonical contract consumption and deviations. A generated kit.json helps scope a task but replaces neither lock. See Agent integration and Versioning.

Implementation is not acceptance evidence

Availability, maturity, demonstrated states, implemented tests and actual passing runs are separate facts. tested is a compatibility alias for testImplemented, not a pass. Your application must still exercise its integrated behavior. See Verification.

Sources: theme manifest, identity, architecture.