HELM AI Kernel Design System Surface

This page documents the public HELM AI Kernel console and design-system surface. It exists so the docs site covers the frontend package family instead of burying it inside repository-only package READMEs.

Audience

This page is for contributors extending the HELM AI Kernel Console, maintainers reviewing frontend package changes, and developers who need to understand which UI assets are part of the self-hostable OSS surface.

Outcome

You should know which packages and docs own console UI primitives, how the design-system package is validated, and where the public console docs fit into the larger HELM AI Kernel developer journey.

Surface Model

flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        console["HELM AI Kernel Console"]
        package["packages/design-system-core"]
        docs["docs/design-system/*"]
        public["Public console docs"]
        release["Self-hostable OSS release"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        tests["package tests and CI gates"]
    end

    %% Operational Flow Edges
    console --> package
    package --> docs
    docs --> tests
    tests --> public
    public --> release

    %% Premium Styling Rules
    style tests fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff

flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        console["HELM AI Kernel Console"]
        package["packages/design-system-core"]
        docs["docs/design-system/*"]
        public["Public console docs"]
        release["Self-hostable OSS release"]
    end

    subgraph Evaluation["2. Evaluation & Policy Plane"]
        tests["package tests and CI gates"]
    end

    %% Operational Flow Edges
    console --> package
    package --> docs
    docs --> tests
    tests --> public
    public --> release

    %% Premium Styling Rules
    style tests fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff

Source Families

Validation

Use the package and docs gates before changing console or design-system behavior:

make test-design-system
make test-console
make docs-coverage docs-truth

The design system is part of the OSS self-hostable surface, but it is not a separate product. Public docs should explain how it supports the Console and developer experience, not position it as a standalone commercial UI kit.

Source Truth

• apps/console/
• packages/design-system-core/README.md
• docs/design-system/README.md
• docs/design-system/accessibility.md
• docs/design-system/architecture.md
• docs/design-system/ci-gates.md
• docs/CONSOLE.md

Troubleshooting

Documentation And UI Contract

The design system docs should connect visual components to governance meaning. Status badges, receipt summaries, policy decisions, warnings, and verifier output must use stable labels that match schemas and CLI output. When a token or component changes, update screenshots, accessibility notes, and any consuming Console or docs-platform page together. A reader should know which styles are illustrative, which are required for accessible evidence review, and which are outside the OSS surface. Keep color and icon decisions tied to state semantics such as allow, deny, warning, pending verification, and stale evidence rather than decorative preference.

Include keyboard focus, color contrast, reduced-motion behavior, and copy semantics for each stateful component. Evidence review UI must remain usable in screenshots, Markdown exports, and assistive technology.

State ownership for token changes and keep component examples aligned with generated screenshots.