@amedia/brick-mcp 0.1.3 → 0.1.4

package/data/components/brick-toggle.md

@@ -0,0 +1,268 @@
+---
+name: brick-toggle
+version: 3.1.14
+selector: brick-toggle-v3
+category: Forms
+tags: [toggle, switch, checkbox, button, form-control, binary, state]
+use_cases: [settings, preferences, feature-toggles, binary-options, form-inputs]
+related: [brick-icon, brick-tokens, brick-template]
+---
+
+# Brick Toggle
+
+A customizable toggle switch component with two visual variants (toggle and button), optional icons, and analytics tracking support.
+
+## Key Capabilities
+
+- Two visual variants: toggle switch and button
+- On/off state management
+- Optional custom text for on/off states
+- Optional icons for on/off states
+- Accessible with ARIA labels
+- ADP analytics integration
+- Keyboard accessible
+- Checked state persistence
+- Server-side rendering support
+
+## Props/Attributes
+
+| Attribute             | Type                     | Default  | Required | Description                                         |
+| --------------------- | ------------------------ | -------- | -------- | --------------------------------------------------- |
+| `data-key`            | string                   | -        | yes      | Unique identifier for the toggle                    |
+| `data-label`          | string                   | -        | no       | Label text for the toggle                           |
+| `data-aria-label`     | string                   | -        | no       | ARIA label for accessibility                        |
+| `data-version`        | `"toggle" \| "button"`   | `toggle` | no       | Visual variant style                                |
+| `checked`             | boolean                  | `false`  | no       | Initial checked state                               |
+| `data-on-text`        | string                   | -        | no       | Custom text when toggle is on                       |
+| `data-off-text`       | string                   | -        | no       | Custom text when toggle is off                      |
+| `data-on-icon-id`     | string                   | -        | no       | Icon ID from brick-icon when toggle is on           |
+| `data-off-icon-id`    | string                   | -        | no       | Icon ID from brick-icon when toggle is off          |
+| `data-adp-clicklabel` | string                   | -        | no       | ADP analytics click label                           |
+
+## Examples
+
+### Basic Toggle Switch
+
+```html
+<brick-toggle-v3
+  data-key="notifications"
+  data-label="Enable Notifications"
+>
+</brick-toggle-v3>
+```
+
+### Pre-checked Toggle
+
+```html
+<brick-toggle-v3
+  data-key="dark-mode"
+  data-label="Dark Mode"
+  checked
+>
+</brick-toggle-v3>
+```
+
+### Button Variant
+
+```html
+<brick-toggle-v3
+  data-key="subscribe"
+  data-label="Subscribe to Newsletter"
+  data-version="button"
+>
+</brick-toggle-v3>
+```
+
+### With Custom On/Off Text
+
+```html
+<brick-toggle-v3
+  data-key="autoplay"
+  data-label="Autoplay Videos"
+  data-on-text="On"
+  data-off-text="Off"
+>
+</brick-toggle-v3>
+```
+
+### With Icons
+
+```html
+<brick-toggle-v3
+  data-key="sound"
+  data-label="Sound"
+  data-on-icon-id="volume-on"
+  data-off-icon-id="volume-off"
+>
+</brick-toggle-v3>
+```
+
+### With Analytics
+
+```html
+<brick-toggle-v3
+  data-key="marketing"
+  data-label="Marketing Emails"
+  data-adp-clicklabel="marketing-consent-toggle"
+>
+</brick-toggle-v3>
+```
+
+### ARIA Label (No Visible Label)
+
+```html
+<brick-toggle-v3
+  data-key="compact-view"
+  data-aria-label="Toggle compact view"
+>
+</brick-toggle-v3>
+```
+
+## Programmatic Usage
+
+```javascript
+const toggle = document.querySelector('brick-toggle-v3');
+
+// Get checked state
+const isChecked = toggle.checked;
+
+// Set checked state
+toggle.checked = true;
+
+// Listen for change events
+toggle.addEventListener('change', (event) => {
+  console.log('Toggle state:', event.target.checked);
+});
+```
+
+## Server-Side Rendering
+
+```javascript
+import { renderBrickToggle } from '@amedia/brick-toggle/template';
+
+const html = renderBrickToggle({
+  dataKey: 'notifications',
+  dataLabel: 'Enable Notifications',
+  dataVersion: 'toggle',
+  checked: false,
+  dataOnText: 'Enabled',
+  dataOffText: 'Disabled',
+});
+```
+
+## Accessibility
+
+- Proper checkbox semantics
+- ARIA label support via `data-aria-label`
+- Keyboard accessible (Space to toggle)
+- Focus visible states
+- State announcements for screen readers
+- Visual and programmatic state indication
+
+## Common Patterns
+
+### Settings Panel
+
+```html
+<div class="settings">
+  <brick-toggle-v3
+    data-key="dark-mode"
+    data-label="Dark Mode"
+    checked
+  ></brick-toggle-v3>
+
+  <brick-toggle-v3
+    data-key="notifications"
+    data-label="Push Notifications"
+  ></brick-toggle-v3>
+
+  <brick-toggle-v3
+    data-key="autoplay"
+    data-label="Autoplay Videos"
+  ></brick-toggle-v3>
+</div>
+```
+
+### Feature Toggles
+
+```html
+<brick-toggle-v3
+  data-key="experimental-feature"
+  data-label="Enable Experimental Features"
+  data-version="button"
+></brick-toggle-v3>
+```
+
+### Volume Control
+
+```html
+<brick-toggle-v3
+  data-key="mute"
+  data-aria-label="Mute audio"
+  data-on-icon-id="volume-on"
+  data-off-icon-id="volume-off"
+  data-version="button"
+></brick-toggle-v3>
+```
+
+## Framework Integration
+
+### Svelte
+
+```svelte
+<script>
+  let darkMode = false;
+
+  function handleToggle(event) {
+    darkMode = event.target.checked;
+  }
+</script>
+
+<brick-toggle-v3
+  data-key="dark-mode"
+  data-label="Dark Mode"
+  checked={darkMode}
+  on:change={handleToggle}
+/>
+```
+
+### React
+
+```jsx
+function Settings() {
+  const [enabled, setEnabled] = useState(false);
+
+  return (
+    <brick-toggle-v3
+      data-key="feature"
+      data-label="Enable Feature"
+      checked={enabled}
+      onChange={(e) => setEnabled(e.target.checked)}
+    />
+  );
+}
+```
+
+## Technical Details
+
+- **Custom Element**: `brick-toggle-v3`
+- **Base Class**: BrickElement
+- **Dependencies**:
+  - @amedia/brick-icon (for icon support)
+  - @amedia/brick-template (base class)
+  - @amedia/brick-tokens (design tokens)
+- **Renders as**: `<input type="checkbox">` with custom styling
+- **SSR Compatible**: Yes, with template function
+
+## Important Notes
+
+- The `data-key` is required and should be unique within the form/page
+- State changes emit standard `change` events
+- The `checked` property/attribute controls the state
+- Icons require valid brick-icon IDs
+- Button variant provides different visual styling but same functionality
+- Analytics tracking via `data-adp-clicklabel` integrates with ADP
+
+## Version
+
+Current version: 3.1.14

package/data/components/brick-tokens.md

@@ -0,0 +1,287 @@
+---
+name: brick-tokens
+version: 6.0.0
+selector: N/A
+category: Utilities
+tags: [design-tokens, css, styling, themes, colors, spacing, typography, shadows]
+use_cases: [theming, consistent-styling, design-system, css-variables, component-styling]
+related: [brick-themes, brick-template, brick-classnames]
+---
+
+# Brick Tokens
+
+The foundational design tokens package providing colors, spacing, typography, shadows, and other design primitives for the Brick design system, with Stitches CSS-in-JS integration and theme support.
+
+## Key Capabilities
+
+- Comprehensive design token system (colors, spacing, typography, shadows, borders)
+- Multiple publication themes (Alfa, Bergen, BT, etc.)
+- CSS custom properties generation
+- Stitches CSS-in-JS integration
+- Style Dictionary based token transformation
+- TypeScript type definitions
+- CDN distribution via Eik
+- Framework-agnostic
+
+## Core Token Categories
+
+### Colors
+
+- Text colors (primary, secondary, tertiary)
+- Background colors
+- Border colors
+- Utility colors (success, warning, error, info)
+- Theme-specific publication colors
+
+### Spacing
+
+- Consistent spacing scale
+- Padding tokens
+- Margin tokens
+- Gap tokens
+- Inset tokens
+
+### Typography
+
+- Font families
+- Font sizes
+- Font weights
+- Line heights
+- Letter spacing
+
+### Shadows
+
+- Elevation shadows
+- Focus shadows
+- Component-specific shadows
+
+### Borders
+
+- Border widths
+- Border radii
+- Border styles
+
+## Examples
+
+### Using with Stitches (CSS-in-JS)
+
+```javascript
+import { css } from '@amedia/brick-tokens';
+
+const button = css({
+  color: '$supportiveBlackText',
+  backgroundColor: '$supportiveBlackBg',
+  padding: '$spacing-m',
+  borderRadius: '$radii-button',
+  fontSize: '$fontSize-body',
+});
+```
+
+### Using CSS Custom Properties
+
+```css
+.my-component {
+  color: var(--brick-colors-textPrimary);
+  background-color: var(--brick-colors-bgPrimary);
+  padding: var(--brick-spacing-m);
+  border-radius: var(--brick-radii-button);
+  font-size: var(--brick-fontSize-body);
+}
+```
+
+### Importing Theme Styles
+
+```javascript
+// Import base tokens
+import '@amedia/brick-tokens';
+
+// Import specific theme
+import '@amedia/brick-tokens/dist/themes/bergen/index.js';
+```
+
+### Using in Components
+
+```typescript
+import { css } from '@amedia/brick-tokens';
+import { BrickElement, defineCustomElement } from '@amedia/brick-template';
+
+const titleClass = css({
+  color: '$textPrimary',
+  fontSize: '$fontSize-heading-l',
+  fontWeight: '$fontWeight-bold',
+  marginBottom: '$spacing-l',
+});
+
+@defineCustomElement({
+  selector: 'my-component',
+})
+class MyComponent extends BrickElement {
+  get HTML() {
+    return `<h1 class="${titleClass}">Hello</h1>`;
+  }
+}
+```
+
+## Token Access Patterns
+
+### Via Stitches
+
+```javascript
+import { css, theme } from '@amedia/brick-tokens';
+
+// Using in css function
+const styles = css({
+  color: '$textPrimary',
+  padding: '$spacing-m',
+});
+
+// Accessing token values
+const primaryColor = theme.colors.textPrimary;
+```
+
+### Via CSS Variables
+
+```html
+<style>
+  .custom-button {
+    background: var(--brick-colors-buttonPrimaryBg);
+    color: var(--brick-colors-buttonPrimaryFg);
+    padding: var(--brick-spacing-s) var(--brick-spacing-m);
+  }
+</style>
+```
+
+## Theme System
+
+Brick tokens supports multiple publication themes:
+
+```javascript
+// Available themes
+import '@amedia/brick-tokens/dist/themes/alfa/index.js';
+import '@amedia/brick-tokens/dist/themes/bergen/index.js';
+import '@amedia/brick-tokens/dist/themes/bt/index.js';
+// ... and more
+```
+
+Each theme provides:
+- Publication-specific color palettes
+- Brand colors
+- Typography settings
+- Spacing overrides (if needed)
+
+## Build Output
+
+The package provides multiple formats:
+
+- **ES Modules**: `dist/index.mjs`
+- **Stitches**: `dist/stitches.js`
+- **CSS**: `dist/css/**`
+- **Themes**: `dist/themes/*`
+- **Style Dictionary**: `build/style-dictionary/**`
+- **TypeScript Types**: `dist/index.d.ts`
+
+## CDN Usage
+
+```html
+<!-- Load tokens via Eik CDN -->
+<script src="https://assets.acdn.no/pkg/@amedia/brick-tokens/6.0.0/brick-tokens.js" type="module"></script>
+
+<!-- Load specific theme -->
+<script src="https://assets.acdn.no/pkg/@amedia/brick-tokens/6.0.0/themes/bergen/index.js" type="module"></script>
+
+<!-- Load CSS variables -->
+<link rel="stylesheet" href="https://assets.acdn.no/pkg/@amedia/brick-tokens/6.0.0/css/tokens.css">
+```
+
+## Common Token Examples
+
+### Spacing Tokens
+
+```javascript
+const spacing = {
+  xs: '$spacing-xs',  // Extra small
+  s: '$spacing-s',    // Small
+  m: '$spacing-m',    // Medium
+  l: '$spacing-l',    // Large
+  xl: '$spacing-xl',  // Extra large
+};
+```
+
+### Color Tokens
+
+```javascript
+const colors = {
+  // Text
+  textPrimary: '$textPrimary',
+  textSecondary: '$textSecondary',
+
+  // Backgrounds
+  bgPrimary: '$bgPrimary',
+  bgSecondary: '$bgSecondary',
+
+  // Utilities
+  success: '$utilitySuccessBg',
+  error: '$utilityErrorBg',
+  warning: '$utilityWarningBg',
+};
+```
+
+### Typography Tokens
+
+```javascript
+const typography = {
+  // Font sizes
+  headingL: '$fontSize-heading-l',
+  headingM: '$fontSize-heading-m',
+  body: '$fontSize-body',
+
+  // Font weights
+  bold: '$fontWeight-bold',
+  regular: '$fontWeight-regular',
+
+  // Line heights
+  tight: '$lineHeight-tight',
+  normal: '$lineHeight-normal',
+};
+```
+
+## Development
+
+### Transform Tokens
+
+```bash
+npm run transform-figma  # Transform Figma tokens
+npm run style-dictionary # Build Style Dictionary
+npm run build:tokens     # Build all tokens
+```
+
+### Validation
+
+```bash
+npm run validate  # Validate CSS files
+```
+
+## Technical Details
+
+- **Package Type**: Design tokens and CSS-in-JS utilities
+- **Token Format**: Style Dictionary compatible
+- **CSS-in-JS**: Stitches integration
+- **TypeScript**: Full type definitions
+- **Dependencies**:
+  - @amedia/brick-classnames (utility classes)
+  - @amedia/brick-themes (theme definitions)
+  - @stitches/core (CSS-in-JS runtime)
+
+## Important Notes
+
+- Version 6.0.0 is the current stable version
+- Tokens are generated from Figma via tokens-studio
+- All tokens follow consistent naming conventions
+- CSS custom properties use `--brick-*` prefix
+- Stitches tokens use `$` prefix
+- Themes override base tokens with publication-specific values
+- The package is used by all Brick components for consistent styling
+
+## Version
+
+Current version: 6.0.0