Spec: KDS sidebar order

Defines the *rdering 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 *lphabetical order by slug*(the URL segment passed to @SidebarLink), *ocale-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:

*wnerdecision pending* the four `Grandfathered 202605-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 toolsdesign-genbacklogpending018…kmd` followup 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):

Discovery for new mirrors *implemented 20260518, R3autodiscovery check)* the audit walks `toolsdesign-geninternal/kinds