Documentation 0.7: Theming Guide, Layout Cookbook, Migration 0.6 → 0.7

[ZhukMax]

Author, organize, and ship the documentation set for EFx 0.7. This includes a first-class Theming Guide, a practical Layout Cookbook, and a Migration 0.6 → 0.7 note. All code snippets must compile (doctests or examples), and new examples should build for wasm32-unknown-unknown (build-only, no runtime).

---

Motivation

• Make new 0.7 features (theming, tokens, scoped styles, layout shorthands, Tabs/Table) approachable with clear, runnable examples.
• Reduce support overhead by documenting common patterns and gotchas.
• Provide a frictionless upgrade path from 0.6 to 0.7.

---

Scope

• New docs:

  • docs/theming.md — tokens, presets/classes, efx_theme!, scoped overrides.
  • docs/cookbook.md — layout shorthands, Tabs/Table (behind extras), common UI patterns.
  • docs/migration-0.6-0.7.md — what changed, deprecations (if any), mappings/recipes.

• Updates:

  • Link these pages from README.md and docs/tags.md where relevant.
  • Reference examples in examples/ and/or sandbox scenes.

• CI:

  • Ensure all code blocks compile (doctest/trybuild) where feasible.
  • Ensure examples referenced by docs build for wasm32-unknown-unknown.

---

Proposed structure (sketch)

docs/theming.md

• Overview: goals, concepts (design tokens, classes, scopes).

• Quick start (minimal theme + install):

  let theme = efx_theme! {
      palette  { primary: "#3b82f6", fg: "#e5e7eb", bg: "#0b0b0f" }
      spacing  { sm: 8, md: 12, lg: 16 }
      radius   { sm: 4, md: 8, lg: 12 }
      typography {
        h1 { size: 24, weight: 700 }
        body { size: 14, weight: 400 }
      }
      classes {
        h1 { font: "h1", color: "fg", m: "sm" }
        primary { color: "palette.primary", weight: 600 }
      }
  };
  efx::set_theme(theme);

• Using classes & tokens in templates:

  efx!(ui, r#"
    <Column p="spacing.lg" gap="spacing.md">
      <Heading class="h1">Title</Heading>
      <Button class="primary" rounding="radius.lg">OK</Button>
    </Column>
  "#);

• Scoped styles (theme="dark" or inline overrides):

  efx!(ui, r#"
    <Row theme="{ palette: { primary: '#ff7a00' } }">
      <Label class="muted">Scoped accent</Label>
    </Row>
  "#);

• Diagnostics: unknown tokens/classes → suggestions; best practices.

docs/cookbook.md

• Layout shorthands (m*, p*, align, align_x/align_y) with tables and short examples.

• Patterns:

  • Card with header/body/footer and padding shorthands.
  • Toolbar + primary/secondary buttons.
  • Form snippet (labels, TextField, validation message).
  • Tabs (behind extras): switching content sections.
  • Table (behind extras): header, rows, zebra stripes.

• Link to runnable examples in examples/ or sandbox scenes.

docs/migration-0.6-0.7.md

• What’s new (theming, tokens, shorthands, Tabs/Table).

• Changes & compatibility:

  • Token aliases as drop-in replacements for numeric literals.
  • Where shorthands supersede verbose attributes; precedence rules.
  • Color parser additions (short hex, names) — if present in 0.7.

• Recipes: mapping common 0.6 snippets to 0.7 syntax.

• Checklist for upgrading a project.

---

Tasks

• Create docs/theming.md with runnable snippets (doctest or example links).
• Create docs/cookbook.md with concise, copy-pasteable patterns.
• Create docs/migration-0.6-0.7.md with side-by-side before/after.
• Update README.md with “What’s new in 0.7” + links to the above.
• Update docs/tags.md to reference tokens/shorthands where relevant.
• Add/adjust examples/ (or sandbox scenes) used by the docs.
• CI: ensure doc code compiles (doctest/trybuild) and examples build for wasm32-unknown-unknown.
• Proofread & validate internal links; run a markdown linter.