Skip to content

docs: fix palette explorer export and frame the palettes page#629

Draft
johnleider wants to merge 1 commit into
masterfrom
worktree-docs-palettes-export
Draft

docs: fix palette explorer export and frame the palettes page#629
johnleider wants to merge 1 commit into
masterfrom
worktree-docs-palettes-export

Conversation

@johnleider

Copy link
Copy Markdown
Member

Problem

The /guide/features/palettes page rated poorly for being confusing. Root cause was the interactive explorer at the top of the page:

  • Copy Config emitted dead code. onExport produced a colors block where every line was commented out — pasting the output gave a theme with no colors defined (silent no-op). The click path was worse: it emitted bare token strings with no role key, which are a syntax error once uncommented.
  • The widget had no instructions. It's the first thing on the page, dropped in after a single sentence, with no explanation of click-to-copy, what Copy Config does, or why the grid flips orientation on Material.
  • Static-vs-generator and the {palette.…} token syntax were never framed before the widget.

Changes

  • onExport now emits real, uncommented config. Clicked swatches map to theme roles (primary, secondary, …) in click order; the no-click default seeds primary/secondary from hues that actually exist in the selected palette (the old default hardcoded blue.500/slate.600, which don't exist outside Tailwind).
  • In-widget hint explaining click-to-copy → Copy Config.
  • Framing prose above the explorer: static vs generator forms, the token-reference syntax with a link to Theming, and a note that shade-heavy palettes (Material) render transposed.

Verification

  • Export code-gen validated in isolation — both the no-click and multi-click branches produce valid, resolvable config.
  • vue-tsc on apps/docs: 0 errors. ESLint clean.
  • Not yet driven in a live browser — the generated-string logic is verified, but a click-through confirmation is worth doing before merge.

The palette explorer's Copy Config button emitted a fully commented-out
colors block, so pasting its output produced a theme with no colors; the
click path emitted keyless token lines that were invalid once uncommented.

onExport now emits real, uncommented config: clicked swatches map to theme
roles in click order, and the no-click default seeds primary/secondary from
hues that actually exist in the selected palette so the reference resolves.

Adds framing prose above the explorer (static vs generator, token-reference
syntax, axis-flip note) and an in-widget hint explaining click-to-copy.
@johnleider johnleider added this to the v1.0.0 milestone Jul 17, 2026
@johnleider johnleider added the documentation Improvements or additions to documentation label Jul 17, 2026
@johnleider johnleider self-assigned this Jul 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant