Spec — Per-platform code samples toggle

Facet Develop of Koder Design. Material parity: https://m3.material.io/develop (cross-cutting toggle pattern).

What it does

Every component reference page (e.g., /reference/components-buttons.html) shows code samples. A toggle above the first code block switches the visible language for ALL code blocks on the page in unison:

Code samples:  [Flutter] [Compose] [SwiftUI] [Web]
                  ↑ selected
                  v

Selection persists across navigation: visiting another component page shows the same platform's code by default.

R1 — Platforms

v1 ships 4 platforms: flutter, compose, swiftui, web. Adding a 5th platform = add token + render adapter; no other changes.

R2 — Toggle layout

Toggle appears as a segmented button row (per components/buttons.kmd § segmented buttons):

┌──────────────────────────────────────────────┐
│  Code samples:                                │
│  ┌──────┐┌────────┐┌─────────┐┌────────┐    │
│  │Flutter││Compose ││ SwiftUI ││  Web   │    │
│  └──────┘└────────┘└─────────┘└────────┘    │
└──────────────────────────────────────────────┘

Position: sticky to top of page on scroll (so users don't lose access when reading later sections).

Mobile (Compact): becomes a dropdown menu (per components/menus.kmd exposed-dropdown).

R3 — Code block rendering

Each code block in the page authoring source declares its platform:

## Example

```{platform=flutter}
KoderButton(
  variant: KoderButtonVariant.filled,
  label: 'Save',
  onPressed: () => print('Saved'),
)

KoderButton(
    variant = KoderButtonVariant.Filled,
    label = "Save",
    onClick = { Log.d("App", "Saved") }
)

KoderButton("Save", variant: .filled) {
    print("Saved")
}

<koder-button variant="filled" onclick="console.log('Saved')">
  Save
</koder-button>

Renderer:
- Groups blocks by author-defined sample ID (or position)
- Shows only the selected platform's block
- Hides others via CSS `display: none` (still in DOM for SEO + screen
  readers can read all via prefer-show-all toggle)

## R4 — Default platform

Default platform is **Flutter** (current Koder primary). Override:
- URL param `?platform=compose` → that platform pre-selected on load
- LocalStorage: last user choice persists per browser
- URL param wins over LocalStorage

## R5 — Author requirement

Each component spec / reference page **MUST** include code samples
for ALL v1 platforms. If a platform doesn't yet support a component
(e.g., Compose not yet shipping `KoderCarousel`), show:

ℹ️ Not yet available in Compose. Track progress: engines/sdk/koder-design-compose#XXX

Authoring guide: see `meta/docs/stack/specs/docs/authoring.kmd`
(separate file, future).

## R6 — Copy button

Each code block has a copy button at top-right (regardless of
visibility):
- Tap → copies the active platform's code to clipboard
- Confirms via snackbar: "Copied Flutter sample" (per
  `components/snackbars.kmd`)

## R7 — Accessibility

- Toggle: segmented button group with full ARIA semantics (see
  `components/buttons.kmd § segmented`)
- Code blocks: `<pre><code>` with `lang` attribute (`lang-dart`,
  `lang-kotlin`, `lang-swift`, `lang-html`)
- Screen reader announces toggle change: "Code samples switched to
  Compose"
- Show-all-platforms mode (button in toggle row): expands all blocks
  vertically; useful for translators / accessibility users

## R8 — Performance

- All platform variants ship in HTML (no client-side fetch on
  toggle)
- Page size impact: ~2-3× larger HTML, but typically still < 200 KB
  for a component page
- CSS-based show / hide: instant; no layout reflow

## R9 — Forbidden patterns

- ❌ Code samples missing for any v1 platform (every component
  page must cover all 4)
- ❌ Pseudocode or rough sketches as code samples (must compile /
  type-check)
- ❌ Per-platform toggle hidden when only one platform supports a
  component (still show the toggle with stubs for the unsupported
  platforms — sets honest expectation)
- ❌ Code samples without copy button
- ❌ Code samples without `lang` attribute (breaks syntax highlighter)
- ❌ Hardcoded color hex / token values in samples (always reference
  `KoderDesignTheme` / `LocalKoderTokens` / equivalent)

## Cross-link

- `develop/android-compose.kmd` — Compose surface for code samples
- `develop/ios-swiftui.kmd` — SwiftUI surface
- `components/buttons.kmd` — segmented button pattern (toggle)
- `components/menus.kmd` — dropdown variant on Compact width
- `components/snackbars.kmd` — copy confirmation
- Generator code: `tools/design-gen/internal/markdown/codeblock.go`
  (handles `{platform=…}` directive)