From 6ad9f448859e030fc415d6e185390914baca890d Mon Sep 17 00:00:00 2001 From: Thomas Decaux Date: Sun, 28 Jun 2026 15:36:10 +0200 Subject: [PATCH 01/18] docs: design spec for toggleable card theme Co-Authored-By: Claude Opus 4.8 --- .../specs/2026-06-28-card-theme-design.md | 138 ++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 docs/superpowers/specs/2026-06-28-card-theme-design.md diff --git a/docs/superpowers/specs/2026-06-28-card-theme-design.md b/docs/superpowers/specs/2026-06-28-card-theme-design.md new file mode 100644 index 0000000..286c6e5 --- /dev/null +++ b/docs/superpowers/specs/2026-06-28-card-theme-design.md @@ -0,0 +1,138 @@ +# Card UI theme — design + +## Goal + +Ship a small, opinionated "minimal but beautiful" card theme for the +`@ebuildy/docusaurus-plugin-gitlab` components. It must be: + +- **Toggleable from plugin config** with a single boolean — no token tuning. +- **Light/dark aware**, following the host site's active Docusaurus theme. +- **Pure CSS / SSR-safe** — no client JS, no flash, consistent with the + build-time / static-HTML philosophy in `CLAUDE.md`. + +## Non-goals + +- No configurable design tokens (accent, radius, elevation, density). Explicitly + cut — the theme is one opinionated look. +- No `{ light, dark }` config pairs and no `--gl-card-*` token system. +- No changes to the component `.tsx` files or their class names. +- No automatic MDX component registration (users still register components via + `MDXComponents` as today). +- No *user-facing* design tokens. The internal `--gl-card-*` CSS variables below + are private plumbing, not config — the user only ever sets the boolean. + +## Approach + +Add a **Docusaurus plugin** alongside the existing remark plugin. The components' +CSS module is rewritten so each visual property reads a private internal variable +with a built-in fallback, e.g. +`box-shadow: var(--gl-card-shadow, none)` and +`border-color: var(--gl-card-border, var(--ifm-color-emphasis-300))`. The +fallback values reproduce today's bare look, so with no plugin the cards look +exactly as they do now. + +When the plugin is enabled it injects a single inline `