@app-studio/components 0.10.17

package/docs/design-system/theming.md

@@ -0,0 +1,336 @@
+# Theming Guide
+
+This guide explains how the design-system theming layer works end-to-end: the providers, the tokens you can reference, and how brand-specific values get propagated to every component without you wiring anything per-brand.
+
+For the architectural overview and how to author components against this system, see [component-library.md](./component-library.md).
+
+---
+
+## 1. Two providers — what does what
+
+The app uses two cooperating providers, set up once at the root in [src/providers/index.tsx](../../src/providers/index.tsx):
+
+```tsx
+<ThemeModeContext.Provider value={{ mode, toggleThemeMode }}>
+  <GoogleFontProvider>
+    <ThemeProvider mode={mode} theme={{ primary: 'color-blue-700', secondary: 'color-purple-500' }}>
+      <ResponsiveProvider>
+        <RouterProvider>{children}</RouterProvider>
+      </ResponsiveProvider>
+    </ThemeProvider>
+  </GoogleFontProvider>
+</ThemeModeContext.Provider>
+```
+
+| Provider              | Role                                                                                              |
+|-----------------------|---------------------------------------------------------------------------------------------------|
+| `ThemeProvider`       | App-studio's color-resolver context. Sets the global `themeMode` (`light` / `dark`) and the default `theme-primary` / `theme-secondary` colors. |
+| `ThemeModeContext`    | Local-app toggle between light and dark mode. The `useThemeMode()` hook reads this.               |
+| `GoogleFontProvider`  | Imports the Google Fonts referenced in `metadata.googleFontLinks` (per-brand fonts inject into `<Helmet>`). |
+| `DesignSystemProvider` | **Optional, brand-aware layer.** Drops into any subtree and overrides the theme tokens for that subtree with the active brand's `theme.*` values. |
+
+You can use the design system anywhere by wrapping a subtree in `<DesignSystemProvider config={airbnbConfig}>` (or `configId="airbnb"`). Components below it pick up Airbnb's brand colors via the CSS-variable layer described in §3 — without disturbing the rest of the app.
+
+---
+
+## 2. Theme modes
+
+The app-level mode is a binary `light` / `dark` switch managed by `ThemeModeContext`:
+
+```tsx
+import { useThemeMode } from 'src/providers';
+
+function ModeToggle() {
+  const { mode, toggleThemeMode } = useThemeMode();
+  return <button onClick={toggleThemeMode}>Switch to {mode === 'light' ? 'dark' : 'light'}</button>;
+}
+```
+
+You can also pin a single component to a specific mode using the `themeMode` prop:
+
+```tsx
+<Button themeMode="dark">Always dark</Button>
+<Badge themeMode="light">Always light</Badge>
+```
+
+Brand configs declare their `defaultAppearance` in `metadata` (`light` or `dark`). The design-system showcase respects that when rendering each brand on its native canvas, but also renders an inverted PaletteFrame so you can see how the brand performs on the opposite surface.
+
+---
+
+## 3. How brand tokens flow through app-studio
+
+When a `DesignSystemProvider` mounts, it does two things:
+
+1. Stores the config in React context (so hooks reach the active brand).
+2. **Delegates to app-studio's `<ThemeProvider>`** — passing `theme={config.theme}`, `mode={config.metadata.defaultAppearance}`, and `transparentWrapper` (so the inner provider doesn't repaint the page).
+
+app-studio's `<ThemeProvider>` then:
+- Iterates the `theme` object you gave it and emits one `--theme-<key>` CSS variable per slot (`--theme-primary`, `--theme-canvas`, …).
+- Registers those slots with the color resolver so `getColor('theme-primary')` returns `var(--theme-primary)`.
+- Adds `data-theme="light|dark"` on a div so `[data-theme=…]` color-scale selectors can scope properly.
+
+The DesignSystemProvider also sets `data-design-system="<id>"` and `data-appearance="light|dark"` on a `display:contents` child, purely for downstream CSS hooks.
+
+Inside the subtree, the following CSS variables are live (one per slot in your brand `theme` block):
+
+```
+--theme-primary       (e.g., #FF385C for Airbnb, #1DB954 for Spotify)
+--theme-secondary
+--theme-success
+--theme-warning
+--theme-error
+--theme-canvas
+--theme-surface
+--theme-text
+--theme-muted
+--theme-border
+--theme-onPrimary
+```
+
+You don't write `var(--theme-primary)` in components — you write `'theme-primary'`. App-studio's resolver — same code path as for `color-blue-500` and any other token — turns that into `var(--theme-primary)` at render time, which the browser resolves to the brand's hex. The component code doesn't know which brand is active and doesn't have to.
+
+### 3.1 Why this matters
+
+The resolver, not the DesignSystemProvider, is the bridge. That means every code path in app-studio that already handles `theme-*` tokens — alpha suffixes (`theme-primary-100` = 10% mix), token references in theme objects (`theme.primary: 'color-blue-700'` chains correctly), `getColor` / `getColorHex` / `getColorRGBA` helpers, the `useTheme` hook — automatically works for brand tokens too. There's no parallel resolution layer to maintain.
+
+### 3.2 Pseudo-element / browser pseudo-class styling
+
+For things that have historically required a `.css` file — `::placeholder`, `::selection`, `:-webkit-autofill`, `::-webkit-contacts-auto-fill-button`, browser spinner buttons — use app-studio's `_*` props. The resolver handles theme tokens the same way it does for regular props.
+
+```tsx
+<Input
+  _placeholder={{ color: 'color-gray-400', opacity: 1 }}
+  _focus={{ _placeholder: { opacity: 0.7 } }}
+  _selection={{ backgroundColor: 'theme-primary-200' }}
+  _webkitAutofill={{
+    boxShadow: '0 0 0 1000px theme-canvas inset',
+    WebkitTextFillColor: 'theme-text',
+  }}
+/>
+```
+
+Supported pseudos include `_hover`, `_focus`, `_active`, `_focusVisible`, `_focusWithin`, `_disabled`, `_checked`, `_placeholder`, `_selection`, `_before`, `_after`, `_marker`, `_backdrop`, `_webkitAutofill`, `_webkitContactsAutoFillButton`, `_webkitInnerSpinButton`, `_webkitOuterSpinButton`, `_webkitSearchCancelButton`, `_mozPlaceholder`, `_mozFocusInner`, plus group / peer modifiers. Pseudos nest — `_focus={{ _placeholder: {...} }}` compiles to `:focus::placeholder { ... }`.
+
+For alpha tints, prefer the resolver's `theme-primary-100`–`theme-primary-1000` alpha suffix — it generates `color-mix(in srgb, var(--theme-primary) X%, transparent)` internally and stays consistent with the rest of the resolver output.
+
+### 3.3 React inline style
+
+```tsx
+<View style={{ color: 'var(--theme-text)', backgroundColor: 'var(--theme-surface)' }}>
+  ...
+</View>
+```
+
+### 3.4 The `useTheme` hook (app-studio)
+
+```tsx
+import { useTheme } from 'app-studio';
+
+function Snippet() {
+  const { getColor, themeMode } = useTheme();
+  const primary = getColor('theme-primary', { themeMode });   // → 'var(--theme-primary)'
+  return <View backgroundColor={primary} />;
+}
+```
+
+---
+
+## 4. Token reference
+
+### 4.1 Semantic theme tokens (the eleven slots)
+
+| Token              | Meaning                                              |
+|--------------------|------------------------------------------------------|
+| `theme-primary`    | Brand primary — main CTAs, links, focus rings        |
+| `theme-secondary`  | Brand secondary — supporting accents                 |
+| `theme-success`    | Positive state                                       |
+| `theme-warning`    | Caution / pending state                              |
+| `theme-error`      | Destructive / failure state                          |
+| `theme-canvas`     | Page background                                      |
+| `theme-surface`    | Card / elevated surface background                   |
+| `theme-text`       | Primary ink                                          |
+| `theme-muted`      | Secondary ink (helper, captions, disabled-ish)       |
+| `theme-border`     | Hairlines, dividers, default control borders         |
+| `theme-onPrimary`  | Ink that sits on top of `theme-primary` (button text)|
+
+Every slot has matching alpha-suffix variants: `theme-primary-100` (10% primary) through `theme-primary-1000` (100%). app-studio's resolver renders these as `color-mix(in srgb, var(--theme-primary) X%, transparent)`.
+
+Every brand provides all eleven. Use them in priority over neutral-scale tokens whenever the value should respect the brand.
+
+### 4.2 Neutral / static colors
+
+For things that should stay constant across brands (utility chrome, debug overlays):
+
+- `color-white`, `color-black`
+- `color-gray-50` through `color-gray-900`
+- `color-blue-*`, `color-green-*`, `color-red-*`, `color-yellow-*`, `color-purple-*`, `color-orange-*`, etc.
+
+These don't shift with the active brand. Use them sparingly — anything user-visible should prefer `theme-*`.
+
+### 4.3 The `'inherit'` keyword
+
+For label-style text where the color should track the surrounding ink, use `color: 'inherit'`. The form controls (Checkbox, Radio, Switch, FieldLabel, StatusIndicator, Table cells) all default to `inherit` so they remain readable on any brand surface. Brand configs intentionally **omit** `label.color` to let this work — see [component-library.md §7.2](./component-library.md#72-strip-labelcolor-from-brand-component-configs).
+
+---
+
+## 5. Typography
+
+Each brand sets its own typography stack via `config.tokens.typography`:
+
+```jsonc
+"typography": {
+  "fontFamily": "'Inter', system-ui, sans-serif",
+  "monoFamily": "ui-monospace, SF Mono, monospace",
+  "fontSizes":   ["12px","14px","16px","18px","24px","32px","48px"],
+  "fontWeights": ["300","400","500","600","700","800"],
+  "lineHeights": ["1.0","1.2","1.4","1.6"]
+}
+```
+
+The web fonts those families reference must be listed in `metadata.googleFontLinks` so `<Helmet>` injects the link tag (or shipped locally — Vercel's `Geist` is loaded via Google Fonts as a custom font). Commercial brand fonts (Cereal, sohne, Aeonik, Gotham, Uber Move, Spotify Circular, Shopify Sans) gracefully fall through to Inter or system-ui in the listed chain.
+
+Usage in components:
+
+```tsx
+<Text fontSize={16} fontWeight={500}>Body text</Text>
+<Text fontSize={32} fontWeight={700} letterSpacing="-0.02em">Headline</Text>
+```
+
+Or, for brand-aware code:
+
+```tsx
+import { useDesignSystem } from 'src/design-system';
+
+function BrandedHeadline({ children }: { children: React.ReactNode }) {
+  const { config } = useDesignSystem();
+  return (
+    <Text
+      fontFamily={config.tokens.typography.fontFamily}
+      fontWeight={config.personality?.typeWeight === 'black' ? 800 : 700}
+      letterSpacing={config.personality?.letterSpacing ?? '-0.01em'}
+    >
+      {children}
+    </Text>
+  );
+}
+```
+
+---
+
+## 6. Spacing
+
+The 4-px grid is the unit. Spacing tokens are exposed via `config.tokens.spacing` as a sorted array:
+
+```jsonc
+"spacing": ["2px","4px","8px","12px","16px","24px","32px","56px"]
+```
+
+Components should accept padding/margin via the standard `app-studio` shorthand props (`padding`, `gap`, `marginTop`, …) rather than reading the spacing array. The array is documentation/tooling material.
+
+```tsx
+<View padding={16}>
+  <Horizontal gap={8}>
+    <View width={50} height={50} backgroundColor="theme-primary" />
+    <View width={50} height={50} backgroundColor="theme-secondary" />
+  </Horizontal>
+</View>
+```
+
+---
+
+## 7. Shapes (border radius)
+
+There are three patterns the design system uses:
+
+| Token                | Default | Meaning                                            |
+|----------------------|---------|----------------------------------------------------|
+| `shape="square"`     | `0`     | Sharp corners (Nike, SpaceX, Tesla, Uber, Vercel) |
+| `shape="rounded"`    | `8px`   | Soft corners (most brands)                         |
+| `shape="pill"`       | `9999px`| Fully rounded (Revolut, Spotify)                   |
+
+A component-level config can also pin its own `borderRadius` per slot, e.g., `card.views.container.borderRadius: 12`. The brand-personality block in each config carries the canonical `cardRadius`, `pillRadius`, `badgeRadius` numbers — pages and helpers consume those when assembling brand-shaped compositions.
+
+```tsx
+<Button shape="square">Sharp</Button>
+<Button shape="rounded">Rounded (default)</Button>
+<Button shape="pill">Pill</Button>
+```
+
+---
+
+## 8. Shadows
+
+Shadows come from `config.tokens.shadows` (a sorted array, lightest first). Component-level configs typically pick an index. The `Shadow` prop type covers `'sm' | 'md' | 'lg' | 'xl'` for components that expose a named shadow scale:
+
+```tsx
+<Card shadow="sm">Small shadow</Card>
+<Card shadow="md">Medium shadow</Card>
+<Card shadow="lg">Large shadow</Card>
+```
+
+For bespoke values, pass through `views.container.boxShadow` or inline `style`.
+
+---
+
+## 9. Working with the active design-system config
+
+For pages that need raw access to the brand:
+
+```tsx
+import { useDesignSystem } from 'src/design-system';
+
+function PageWithBrand() {
+  const { config, configId, isEnabled } = useDesignSystem();
+  if (!isEnabled) return null;
+
+  return (
+    <View
+      style={{
+        backgroundColor: config.theme.canvas,
+        color: config.theme.text,
+        fontFamily: config.tokens.typography.fontFamily,
+      }}
+    >
+      <Heading>{config.metadata.label}</Heading>
+    </View>
+  );
+}
+```
+
+To pre-fetch one component's brand config (to compose a custom variant manually):
+
+```tsx
+import { useDesignSystemComponentProps } from 'src/design-system';
+
+function HeroButton() {
+  const buttonConfig = useDesignSystemComponentProps('button');
+  return (
+    <Button views={{ container: { borderRadius: buttonConfig?.views?.container?.borderRadius } }}>
+      Get started
+    </Button>
+  );
+}
+```
+
+For the common pattern of merging brand defaults with the user's explicit props (which is what every component does internally), use `useMergedDesignSystemComponentProps` — see [component-library.md §4.2](./component-library.md#42-public-entry--wire-up-the-design-system).
+
+---
+
+## 10. Best practices
+
+- Reference theme tokens (`theme-primary`, `theme-canvas`, …) instead of literal hex.
+- Don't lock label or helper-text color in brand configs — let `inherit` carry the cascade.
+- Use `views` to override component slots; use top-level props for layout/sizing knobs the component exposes.
+- Use `themeMode` on a single component when you intentionally need it to render light/dark against the page.
+- Follow the 4-px spacing grid.
+- Reach for `config.personality` (cornerStyle, typeWeight, accentTreatment, …) when a page needs brand cues that don't fit into 11 colors and slot styling.
+- Verify any new font is loaded via `metadata.googleFontLinks` — otherwise the chain silently falls through.
+
+---
+
+## See also
+
+- [component-library.md](./component-library.md) — how to author components and brand configs.
+- [src/design-system/types.ts](../../src/design-system/types.ts) — TypeScript types for `DesignSystemConfig`, `BrandPersonality`, all component slot maps.
+- [src/design-system/DesignSystemProvider.tsx](../../src/design-system/DesignSystemProvider.tsx) — provider source incl. CSS-var injection.
+- [src/design-system/configs/](../../src/design-system/configs/) — 15 shipped brand configs.

package/docs/documentation-system.md

@@ -0,0 +1,233 @@
+# Documentation System
+
+This guide explains the documentation system used in the App Studio Components Component Library.
+
+## Overview
+
+The documentation system consists of:
+
+1. **Markdown Documentation**: General guides and tutorials in Markdown format
+2. **MDX Component Documentation**: Interactive component documentation in MDX format
+3. **Automated Documentation Generation**: Tools to generate and update documentation
+
+## Documentation Structure
+
+The documentation is organized into the following directories:
+
+- `docs/`: General documentation and guides
+- `public/files/media/`: MDX component documentation
+- `src/data/props/`: Generated component props data
+
+## MDX Component Documentation
+
+Component documentation is written in MDX format, which allows for interactive examples. Each component has an MDX file in the `public/files/media/` directory.
+
+Example MDX file structure:
+
+```mdx
+# Button
+
+Customizable button for user interaction
+
+### **Import**
+  ```tsx
+  import { Button } from '@app-studio/components';
+  ```
+
+### **Default**
+```tsx
+import React from 'react';
+import { Button } from '../Button';
+
+export const DefaultButton = () => (
+  <Button onClick={() => alert('Hello, World!')}>Default</Button>
+);
+```
+
+### **Props**
+
+| Prop | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| variant | 'filled' \| 'outline' \| 'ghost' \| 'link' | 'filled' | The visual style of the button |
+| size | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' | 'md' | The size of the button |
+```
+
+## Documentation Generation
+
+The documentation system includes tools to automatically generate and update documentation:
+
+### bot-doc
+
+The `bot-doc` tool generates component documentation by analyzing the component code. It:
+
+1. Processes component files to add comments
+2. Generates props data
+3. Creates MDX documentation
+
+To run `bot-doc` for a specific component:
+
+```bash
+npm run bot-doc -- ComponentName src/components/ComponentName
+```
+
+### create-docs
+
+The `create-docs` script checks for components without documentation and generates documentation for them. It also updates documentation for components that have changed.
+
+To run `create-docs`:
+
+```bash
+npm run create-docs
+```
+
+## Documentation Viewing
+
+The documentation can be viewed in the application using the documentation viewer at `/docs`. The documentation viewer:
+
+1. Loads MDX files
+2. Renders them with the MDX provider
+3. Provides a side menu for navigation
+
+## Adding New Documentation
+
+To add new documentation:
+
+1. Create a new Markdown file in the appropriate directory
+2. Add the file to the documentation structure
+3. Link to the file from related documentation
+
+## Updating Component Documentation
+
+To update component documentation:
+
+1. Run `bot-doc` for the component
+2. Review the generated documentation
+3. Make any necessary manual adjustments
+
+## Documentation Maintenance Rules
+
+### Rule 1: Single Source of Truth
+- Each topic should have ONE authoritative documentation file
+- Avoid duplicating content across multiple files
+- Use cross-references instead of copying content
+- **Prohibited**: Creating multiple files covering the same topic
+
+### Rule 2: Clear File Responsibilities
+- **README.md**: Project overview, quick start, navigation to specialized docs
+- **README-ADK.md**: ADK-specific functionality ONLY
+- **docs/README.md**: Documentation hub and navigation
+- **docs/api-integration.md**: Backend integration patterns
+- **Component docs**: Individual component usage and APIs
+
+### Rule 3: Content Validation Checklist
+Before adding/updating documentation:
+- ✅ Check for existing content on the same topic
+- ✅ Verify all code examples work
+- ✅ Ensure links are valid and up-to-date
+- ✅ Follow consistent markdown formatting
+- ✅ Update related files if needed
+- ✅ Remove outdated information
+
+### Rule 4: Mandatory Updates
+Documentation MUST be updated when:
+- Adding new components or features
+- Changing component APIs or props
+- Modifying integration patterns
+- Updating dependencies or requirements
+- Changing project structure
+
+### Rule 5: Quality Standards
+- Use clear, concise language
+- Include practical, working examples
+- Follow consistent formatting and terminology
+- Link related documentation appropriately
+- Test all code examples before publishing
+- Include accessibility information where relevant
+- Document best practices and common pitfalls
+
+## Documentation Best Practices
+
+### Content Organization
+- Keep documentation up-to-date with code changes
+- Include examples for all components and features
+- Use consistent formatting and terminology
+- Link related documentation
+- Test all code examples
+- Include accessibility information
+- Document best practices and common pitfalls
+
+### File Naming Conventions
+- Use kebab-case for file names: `component-development.md`
+- Use descriptive names that clearly indicate content
+- Avoid generic names like `guide.md` or `docs.md`
+
+## Documentation Maintenance Workflow
+
+### Before Making Changes
+1. **Audit existing documentation**:
+   ```bash
+   # Check for duplicate content
+   grep -r "your-search-term" docs/
+
+   # Find broken links
+   find docs/ -name "*.md" -exec grep -l "broken-link" {} \;
+   ```
+
+2. **Validate current structure**:
+   - Ensure no topic is covered in multiple files
+   - Check that all links work
+   - Verify code examples are current
+
+### After Making Changes
+1. **Update related documentation**:
+   - Update cross-references
+   - Check for outdated information
+   - Ensure consistency across files
+
+2. **Run documentation tools**:
+   ```bash
+   npm run create-docs
+   npm run bot-doc -- ComponentName src/components/ComponentName
+   ```
+
+### Regular Maintenance Tasks
+- **Weekly**: Check for broken links and outdated examples
+- **Monthly**: Review documentation structure for redundancies
+- **Per Release**: Update all version-specific information
+
+## Troubleshooting
+
+If you encounter issues with the documentation system:
+
+### Missing Component Documentation
+
+If a component is missing documentation:
+
+```bash
+npm run bot-doc -- ComponentName src/components/ComponentName
+```
+
+### Documentation Not Updating
+
+If documentation is not updating after code changes:
+
+1. Check if the component has changed significantly
+2. Run `bot-doc` manually for the component
+3. Check for errors in the console
+
+### MDX Rendering Issues
+
+If MDX files are not rendering correctly:
+
+1. Check the MDX syntax
+2. Ensure the MDX file is in the correct location
+3. Check for errors in the console
+
+### Duplicate Content Issues
+
+If you find duplicate content:
+
+1. Identify the authoritative source
+2. Remove duplicate content
+3. Add cross-references to the authoritative source
+4. Update any links pointing to removed content