UX behavior and packaged design systems
Example from HELIX’s own docs. This generated page comes from
docs/helix/. Use it to see the method in practice; start with the artifact-type catalog for reusable templates. Historical plans and reports may describe retired architecture.
Source identity (from
02-design/design-ux-governance.md):
ddx:
id: helix.design.ux-governance
authoring:
home: repoUX behavior and packaged design systems
Scope and authority
The operator authorized reusable UX implementation guidance and then required vendor/client-neutral package support on 2026-10-11. HELIX has no dependency on any private design-system implementation. When an applicable design system is available as npm packages, use it. If none is available, retain the selected alternative or let the adopting project write its own concern.
This refines concern propagation, DESIGN.md and story-test-plan coverage. ADR-011 retains Radix/shadcn ownership. No new public skill, runtime CLI, tracker mutation, release or component-library slot is required.
Decisions
- ux-interaction-patterns owns the neutral behavioral baseline. Existing ux-radix/AppKit selections compose it without changing their component owner.
- packaged-design-system owns the generic npm adoption contract. Project evidence supplies actual packages, versions, compatibility, exported APIs, tokens, supported themes, customization points and verification commands. No client, private product, package scope or audit tool is prescribed.
- Available applicable systems are preferred over rebuilding components. Existing selections require an authorized adoption update; unknown fit or unavailable registry access is a recorded question/blocker.
- Resolve competing library/style/toolchain prescriptions through existing project overrides and ADR policy. Compact contexts retain the behavioral floor and selected component owner even with many active concerns.
- DESIGN.md accepts local values or versioned external token references; component wiring belongs in TDs. Embedded/no-navigation views record actual applicability instead of inventing features.
- Optional STP UX Coverage maps six categories to the existing AC/test matrix. Legacy omission remains structurally valid; affected new UI readiness needs adoption. Structure does not prove test existence, execution or behavior.
- Run supplied applicable package checks. When tools are absent, projects define concrete presentation/accessibility checks; actual interaction tests remain separate. No provider, lint framework, audit executable or output path is universal.
Acceptance and ordered implementation
- Neutral and package concerns reach relevant UI/frontend contexts; API-only work and unselected concerns remain unaffected.
- Local and fictional external-package DESIGN examples validate, including explicit absence of page navigation.
- UX coverage positive/negative controls exercise the actual validator.
- Plan/readiness gates name planned tests; completion requires observed results.
- Public templates, examples, generated references and PR text contain no private-system or client-specific integration details from this change.
- Regenerate references/artifacts; run just test, generated-content validation, artifact schemas, pre-commit and diff checks; update the existing PR.
Review and verification scope
Astra ultra reviewed the original UX plan and implementation. Its resolved findings concerned composition compatibility, pattern semantics, structural versus runtime proof, phase sequencing, blank-cell rejection, navigation applicability and compact-context retention. It independently passed 16 UX checks and the diff check. The subsequent operator correction generalizes the package concern, external example and all downstream advice; it does not claim an additional Astra review or consumer runtime run.
The original full just test and pre-commit gates passed. Optional deck rendering
was skipped for missing pptxgenjs; existing seal and advisory warnings matched
the baseline. Current generalized revision: uv run --with pyyaml --python 3.12 just test
exited 0, including all 16 UX tests and 57 catalog examples. Generated-content
validation and schema validation exited 0. The scan of shipped workflow/code
and public content found no private-product/client identifiers introduced by
this change. The optional render skip and baseline warnings remain as above.
Pre-commit runs again on the final commit; no consumer runtime result is claimed.
Innsigle seal: model-primary by HELIX
The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.
- Composition
- model-primary
- Issuer
- HELIX
helix - Signing key
ed25519:b0865d76d834a52c48506414d16f4e5a(build key)- Signed source
artifacts/design-ux-governance.md- Signed
- 2026-11-16T15:52:45Z
- Content digest
sha256:b99f10d3…de72245c
This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.
Raw attestation JSON
{
"payload": {
"innsigle": "1",
"type": "https://innsigle.dev/claim/colophon/v1",
"issued_at": "2026-11-16T15:52:45Z",
"issuer": {
"id": "helix",
"name": "HELIX",
"key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
"key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
},
"subjects": [
{
"uri": "https://documentdrivendx.github.io/helix/artifacts/design-ux-governance/",
"digest": {
"alg": "sha256",
"value": "b99f10d3c741272b50a28a0fe3b5ffc92fe1cb07a8ab4427ffaaee25de72245c"
}
}
],
"colophon": {
"schema_version": "1",
"composition": "model-primary",
"ingredients": [
{
"kind": "model",
"name": "Claude",
"role": "draft"
},
{
"kind": "tool",
"name": "sloptimizer",
"role": "rewrite"
},
{
"kind": "human",
"name": "operator",
"role": "structure-edit"
}
],
"notes": null
}
},
"payload_encoding": "json",
"signatures": [
{
"key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
"alg": "ed25519",
"sig": "m3v1RRa576fz1uqgbY-oZDhmtPS1GxyRPhEWzzGFrJy6qN1arEgAtFCSGA2XY2vetGqZQX3mGn86b0FWe5cuAA",
"signed_at": "2026-11-16T15:52:45Z"
}
]
}