KDS sidebar order

draft

Defines the ordering criterion for entries within each @SidebarGroup of the KDS site sidebar (tools/design-gen/internal/render/layout.templ) and any code-side mirror lists (internal/kinds/<group>.go).

R1 — Default: alphabetical by slug

Within every @SidebarGroup, links MUST be rendered in alphabetical order by slug (the URL segment passed to @SidebarLink), locale-independent.

  • Rationale: scales to N>5 without re-litigating order on each addition;

    applies uniformly across all groups; mechanically auditable in CI; preserves muscle memory across locale switches (slug is locale-stable even though label is translated).

  • The slug list argument to @SidebarGroup(…, "a/", "b/", …) MUST match

    the order of the @SidebarLink(…) calls inside the body, and BOTH MUST be alphabetical.

Worked example:

@SidebarGroup(loc, loc.T("nav.group.foundations"),
    "a11y/", "performance/", "privacy/", "security/", "usability/") {
    @SidebarLink(loc, "a11y/", loc.T("nav.a11y"))
    @SidebarLink(loc, "performance/", loc.T("nav.performance"))
    @SidebarLink(loc, "privacy/", loc.T("nav.privacy"))
    @SidebarLink(loc, "security/", loc.T("nav.security"))
    @SidebarLink(loc, "usability/", loc.T("nav.usability"))
}

R2 — Editorial-order exceptions

A group MAY override R1 with editorial ordering when a semantic sequence exists. Currently grandfathered:

Group slug (i18n key) Justification
nav.group.start (INÍCIO) Onboarding flow: Primeiros passos → Sobre o KDS → Histórico de mudanças. Order is a learning sequence, not an alphabetical surface.
nav.group.styles (Styles) Editorial — current order: verge / style / themes / icons / motion. Grandfathered 2026-05-16: shipped pre-spec via ticket #011; owner has not yet decided whether to alphabetize. Audit treats this as an exception until owner ratifies.
nav.group.components (Components) Editorial — current order: components / patterns / flows / anti-patterns. Grandfathered 2026-05-16: shipped pre-spec via ticket #011. Same status as above.
nav.group.develop (Develop) Editorial — current order: voice / media / coverage / reference. Grandfathered 2026-05-16: shipped pre-spec via ticket #011. Same status as above.
nav.tools (Tools) Editorial — current order: tools / themer / contrast / style-builder / playground / migrate. The first "tools" entry is the catalog index; tools follow. Grandfathered 2026-05-16: shipped pre-spec via ticket #011. Same status as above.

Owner-decision pending: the four Grandfathered 2026-05-16 entries remain as editorial exceptions until owner reviews and either ratifies the editorial order (keeping the exception) or alphabetizes them (removing the exception). Tracked in tools/design-gen/backlog/pending/018-…kmd follow-up section.

Adding a new exception requires updating this table in the same commit as the layout.templ change. The audit script (see R5) treats the table as the source of truth — any group not listed here MUST be alphabetical.

R3 — Mirror lists MUST agree

Code that mirrors a SidebarGroup (e.g. internal/kinds/principle.go:: canonicalPrinciples mirrors the nav.group.foundations group) MUST list entries in the same order as the SidebarGroup, which by R1 is alphabetical unless R2 grants an exception.

Known mirror lists (audit MUST cover all):

Mirror Mirrors group
tools/design-gen/internal/kinds/principle.go::canonicalPrinciples nav.group.foundations

Discovery for new mirrors (implemented 2026-05-18, R3-auto-discovery check): the audit walks `toolsdesign-geninternal/kinds