@discourser/design-system 0.25.3 → 0.27.0

package/docs/context-share/fix-checkbox-radio-tokens.md

@@ -1,145 +0,0 @@
-# Fix: Checkbox, Radio Button, and Input Error State Token Resolution
-
-## Problem Summary
-
-Multiple Park UI recipes reference semantic color tokens (`border`, `error`) as shorthand strings like `borderColor: 'border'` and `borderColor: 'error'`. In Park UI's upstream preset, these are **flat** semantic tokens with a direct `value` property. In the Discourser Design System, they were defined as **nested** tokens (with `default`/`muted` children but no root `value`), which causes Panda CSS to pass the literal string through to CSS instead of resolving it to a CSS variable.
-
-**Affected CSS output (broken):**
-```css
-.checkbox__control { border-color: border; }          /* literal string, not a color */
-.input--variant_outline:is(:invalid) { border-color: error; }  /* same problem */
-```
-
-**Expected CSS output (working):**
-```css
-.checkbox__control { border-color: var(--colors-border); }
-.input--variant_outline:is(:invalid) { border-color: var(--colors-error); }
-```
-
-## Root Cause
-
-In `panda.config.ts`, the semantic token aliases section defines:
-
-```ts
-border: {
-  default: { value: { base: '{colors.gray.6}', _dark: '{colors.gray.6}' } },
-  muted: { value: { base: '{colors.gray.4}', _dark: '{colors.gray.4}' } },
-},
-```
-
-Park UI upstream (`park-ui/packages/preset/src/index.ts`) defines:
-
-```ts
-border: { value: { _light: '{colors.gray.4}', _dark: '{colors.gray.4}' } },
-error: { value: { _light: '{colors.red.9}', _dark: '{colors.red.9}' } },
-```
-
-When Panda CSS encounters `borderColor: 'border'` in a recipe, it looks for a token with a `value` at the `colors.border` path. The Discourser config has no `value` at that level — only `colors.border.default` and `colors.border.muted` exist. Panda falls through and emits the literal string.
-
-The `error` token is **completely missing** from the Discourser config.
-
-## Fix Instructions
-
-### File: `panda.config.ts`
-
-Location: Inside `theme.extend.semanticTokens.colors`, the `border` definition (around line ~130).
-
-**Change the `border` token from:**
-```ts
-border: {
-  default: {
-    value: { base: '{colors.gray.6}', _dark: '{colors.gray.6}' },
-  },
-  muted: {
-    value: { base: '{colors.gray.4}', _dark: '{colors.gray.4}' },
-  },
-},
-```
-
-**To:**
-```ts
-border: {
-  value: { base: '{colors.gray.6}', _dark: '{colors.gray.6}' },
-  default: {
-    value: { base: '{colors.gray.6}', _dark: '{colors.gray.6}' },
-  },
-  muted: {
-    value: { base: '{colors.gray.4}', _dark: '{colors.gray.4}' },
-  },
-},
-```
-
-This adds a root-level `value` that generates `--colors-border` as a CSS variable, while preserving the nested `border.default` and `border.muted` sub-tokens. The root `value` matches `border.default` because that is the semantic equivalent — when recipes say `borderColor: 'border'` they mean the default border color.
-
-**Then add the missing `error` token.** Place it right after the `border` block, before `...m3SemanticTokens`:
-
-```ts
-error: {
-  value: { base: '{colors.red.9}', _dark: '{colors.red.9}' },
-},
-```
-
-This matches Park UI upstream exactly. The `error` token is referenced by Input, Textarea, Select, and other form component recipes for invalid/error states.
-
-### No recipe file changes needed
-
-Do NOT modify any recipe files (`checkbox.ts`, `radio-group.ts`, `input.ts`, etc.). They are character-identical to Park UI upstream and are correct. The fix is entirely in the token definitions.
-
-### No story file changes needed for this fix
-
-The checkbox stories may benefit from adding `colorPalette="primary"` to demonstrate the solid variant's checked state properly, but that is a story improvement, not a bug fix. The rendering fix is the token change above.
-
-## Verification Steps
-
-After making the change:
-
-1. **Rebuild Panda CSS:**
-   ```bash
-   pnpm panda codegen
-   ```
-
-2. **Check that `--colors-border` now exists in the generated CSS.** Look in `styled-system/styles.css` or rebuild Storybook and check the output CSS. You should see:
-   ```css
-   --colors-border: var(--colors-gray-6);
-   --colors-border-default: var(--colors-gray-6);
-   --colors-border-muted: var(--colors-gray-4);
-   --colors-error: var(--colors-red-9);
-   ```
-
-3. **Check checkbox renders with visible border.** The `.checkbox__control` rule should now show:
-   ```css
-   border-color: var(--colors-border);
-   ```
-
-4. **Check input error states work.** The `.input--variant_outline:is(:invalid)` rule should show:
-   ```css
-   border-color: var(--colors-error);
-   ```
-
-5. **Run Storybook** and visually confirm:
-   - Checkbox: unchecked state shows a visible border (gray ring around the box)
-   - Checkbox solid variant: checked state fills with `colorPalette` color
-   - Radio: unchecked state shows a visible circle border (this already works via the `boxShadow` pattern using `gray.surface.border`, but verify no regression)
-   - Input: invalid states show red border
-
-## Scope of Impact
-
-This fix affects every component recipe that references the bare `'border'` or `'error'` token strings. Based on CSS analysis, these components currently have broken token resolution:
-
-**`border` literal (fixed by adding root `value`):**
-- Checkbox (base `control` + solid variant `control`)
-- Stepper (`indicator` border-color)
-- Slider (`track` background — uses `background: border`)
-- Tabs enclosed variant (`--shadow-color: border`)
-
-**`error` literal (fixed by adding `error` token):**
-- Input (outline, surface, subtle, flushed variants — invalid state `border-color`)
-- Textarea (outline, surface, subtle, flushed variants — invalid state)
-- Input flushed variant (`--shadow-color: error` on focus+invalid)
-- Textarea flushed variant (`--shadow-color: error` on focus+invalid)
-
-## Why Radio Buttons Already Work
-
-The radio button recipe uses a different pattern: `boxShadow: 'inset 0 0 0 1px {colors.gray.surface.border}'` with `--shadow-color` set to the fully-qualified token path `gray.surface.border`. This resolves correctly because `gray.surface.border` has a direct `value` in the color palette definitions. No fix needed for radio unchecked state visibility.
-
-If radio buttons appear invisible in Storybook, the issue is likely CSS specificity or a missing `colorPalette` prop on the story — not a token resolution problem. The CSS output for radio is correct: `--shadow-color: var(--colors-gray-surface-border)` which resolves to `var(--colors-neutral-6)` → `#91918B`.

package/docs/context-share/icon-component-prompt.md

@@ -1,154 +0,0 @@
-# Icon Component Creation Prompt
-# Target: Claude Code in Discourser-Design-System repo
-
----
-
-## Task
-
-Create 17 new icon components in the DDS, add them all to the Icons story gallery, add each one to the index, and create a Figma Code Connect file for each.
-
----
-
-## Reference Pattern
-
-Before writing any code, read these files to understand the exact pattern to follow:
-
-- `src/components/Icons/AccountIcon.tsx` — icon component pattern
-- `src/components/Icons/DiscourserLogo.figma.tsx` — Code Connect file pattern
-- `stories/Icons.stories.tsx` — existing story to extend (Gallery story)
-- `src/components/Icons/index.ts` — barrel export to extend
-
-**Component pattern summary:**
-```typescript
-import { ark } from '@ark-ui/react/factory';
-import type { ComponentProps } from 'react';
-import { styled } from 'styled-system/jsx';
-
-const StyledSvg = styled(ark.svg);
-
-export type {ComponentName}Props = ComponentProps<typeof StyledSvg>;
-
-export const {ComponentName} = (props: {ComponentName}Props) => (
-  <StyledSvg
-    viewBox="{viewBox from SVG}"
-    fill="none"
-    xmlns="http://www.w3.org/2000/svg"
-    width="1em"
-    height="1em"
-    {...props}
-  >
-    {/* paths here */}
-  </StyledSvg>
-);
-```
-
-**⚠️ CRITICAL — currentColor rule:**
-Every SVG has hardcoded color values (`#6B7A1F`, `#518500`, `#FFFDFA`, `#F2F2F2`, `#D9E57A`, etc.). These MUST ALL be replaced with `currentColor` so icons inherit color from their parent via the token system. No hardcoded color values anywhere in any component.
-
-- `stroke="#6B7A1F"` → `stroke="currentColor"`
-- `fill="#6B7A1F"` → `fill="currentColor"`
-- `stroke="#FFFDFA"` → `stroke="currentColor"`
-- `fill="#FFFDFA"` → `fill="currentColor"`
-- Any other hardcoded hex → `currentColor`
-
-For icons that use BOTH `fill` and `stroke` on the same path (mixed rendering), use `fill="currentColor"` where fill is the primary visual and `stroke="none"`, or `stroke="currentColor"` and `fill="none"` — match the visual intent of the original. When in doubt, prefer `stroke="currentColor"` with `fill="none"` as that matches the majority of existing icons.
-
-**Code Connect pattern:**
-```typescript
-import figma from '@figma/code-connect';
-import { {ComponentName} } from './{ComponentName}';
-
-figma.connect(
-  {ComponentName},
-  'https://www.figma.com/design/GaHmFfmvO4loUzuZS4TgEz/Discourser.AI--V1?node-id={NODE_ID}',
-  {
-    example: () => <{ComponentName} />,
-  },
-);
-```
-
----
-
-## Icons to Create
-
-All SVG source files are in `docs/context-share/icons/`. Create each component in `src/components/Icons/`.
-
-| SVG File | Component Name | viewBox | Node ID |
-|----------|---------------|---------|---------|
-| `Timer.svg` | `TimerIcon` | `0 0 35 39` | `38-9817` |
-| `ClipBoard.svg` | `ClipBoardIcon` | `0 0 40 39` | `38-9804` |
-| `Microphone.svg` | `MicrophoneIcon` | `0 0 40 45` | `38-9821` |
-| `Audience.svg` | `AudienceIcon` | `0 0 40 44` | `38-9825` |
-| `Record.svg` | `RecordIcon` | `0 0 36 39` | `38-9843` |
-| `NotebookPen.svg` | `NotebookPenIcon` | `0 0 42 42` | `38-9871` |
-| `Sparkles.svg` | `SparklesIcon` | `0 0 24 27` | `38-9872` |
-| `ScrollText.svg` | `ScrollTextIcon` | `0 0 42 42` | `38-9873` |
-| `RepeatQuestion.svg` | `RepeatQuestionIcon` | `0 0 64 63` | `38-9863` |
-| `ExitStudio.svg` | `ExitStudioIcon` | `0 0 64 64` | `38-9853` |
-| `PausePlay.svg` | `PausePlayIcon` | `0 0 64 64` | `38-9849` |
-| `StopPlay.svg` | `StopPlayIcon` | `0 0 64 64` | `38-9857` |
-| `BookmarkPlus.svg` | `BookmarkPlusIcon` | `0 0 42 42` | `38-9870` |
-| `AudioSpeaker.svg` | `AudioSpeakerIcon` | `0 0 40 28` | `38-9812` |
-| `UserProfile.svg` | `UserProfileIcon` | `0 0 42 42` | `38-9874` |
-| `Play.svg` | `PlayIcon` | `0 0 63 63` | `38-9861` |
-| `Speech.svg` | `SpeechIcon` | `0 0 60 60` | `618-5193` |
-
----
-
-## Files to CREATE (per icon — 17 × 2 = 34 files)
-
-For each icon in the table above:
-
-1. `src/components/Icons/{ComponentName}.tsx` — the component
-2. `src/components/Icons/{ComponentName}.figma.tsx` — the Code Connect file
-
----
-
-## Files to UPDATE (2 files)
-
-### 1. `src/components/Icons/index.ts`
-Add an export for every new component:
-```typescript
-export { TimerIcon, type TimerIconProps } from './TimerIcon';
-export { ClipBoardIcon, type ClipBoardIconProps } from './ClipBoardIcon';
-// ... all 17
-```
-
-### 2. `stories/Icons.stories.tsx`
-- Add an import for every new component at the top
-- Add every new icon to the existing `Gallery` story's `HStack` — same pattern as existing icons:
-```tsx
-<VStack gap="2" alignItems="center">
-  <TimerIcon w="6" h="6" color="fg.default" />
-  <span className={label}>TimerIcon</span>
-</VStack>
-```
-
----
-
-## Special Notes Per Icon
-
-**StopPlay** — has a `<rect>` element with `fill="#FFFDFA"`. Replace with `fill="currentColor"`. Keep the `rx="8"` attribute.
-
-**ExitStudio** — has a `<circle>` element with `stroke="#FFFDFA"`. Replace with `stroke="currentColor"` and `fill="none"`.
-
-**PausePlay** — has a `<circle>` with `stroke="#FFFDFA"`. Replace with `stroke="currentColor"` and `fill="none"`.
-
-**Play** — has a `<circle>` outline and triangle path, both `stroke="white"`. Replace both with `stroke="currentColor"` and `fill="none"`.
-
-**Audience** — uses `fill="#6B7A1F"` (not stroke) on all paths. Replace with `fill="currentColor"`. Remove any `stroke` attributes if present. Set top-level `fill` prop to `"currentColor"` instead of `"none"` for this component only.
-
-**ClipBoard** — has two different hardcoded stroke colors (`#6B7A1F` and `#54643F`) on different paths. Replace both with `currentColor` — they should unify to a single color when tokenized.
-
-**RepeatQuestion** — uses `stroke="#F2F2F2"`. Replace with `currentColor`.
-
-**Speech** — uses `stroke="#D9E57A"`. Replace with `currentColor`.
-
----
-
-## Quality Gate
-
-After creating all files, verify:
-- `pnpm type-check` — 0 errors
-- `pnpm build` — builds cleanly
-- No hardcoded hex color values remain in any new component file (grep check: `grep -r "#[0-9A-Fa-f]" src/components/Icons/` should return no new files)