@companycam/slab-web 2.0.5 → 2.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@companycam/slab-web",
-  "version": "2.0.5",
+  "version": "2.0.6",
   "main": "./index.js",
   "module": "./index.mjs",
   "types": "./index.d.ts",

package/skills/using-tokens-web/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: slab/using-tokens-web
+description: >
+  Apply Slab design tokens in a React web app via CSS custom properties.
+  Covers required one-time CSS imports from @companycam/slab-tokens
+  (base.css, light_environment.css, dark_environment.css), CSS variable naming
+  (--cc_color_*, --cc_size_*), web color categories (brand, utility, background,
+  text, button, link, border, depth, label, collab), ccMargin spacing prop on
+  Slab components, spacing/border/text size tokens, and depth (shadow) tokens.
+  Load when writing custom styled-components, applying color or spacing outside
+  a Slab component, or selecting a token value to match a design spec.
+type: core
+library: slab-web
+library_version: '2.0.4'
+sources:
+  - 'CompanyCam/slab:packages/slab-tokens/src/tokens/colors/color.json'
+  - 'CompanyCam/slab:packages/slab-tokens/src/tokens/sizes/size.json'
+  - 'CompanyCam/slab:packages/slab-tokens/dist/css/base.css'
+  - 'CompanyCam/slab:packages/slab-tokens/dist/css/light_environment.css'
+  - 'CompanyCam/slab:packages/slab-web/src/lib/shared/styles.ts'
+---
+
+# Slab Web — Design Tokens
+
+## Setup
+
+Add three CSS imports once in your app's root stylesheet or entry file. All `--cc_*` CSS variables are undefined without them — this is an app-level setup, not per-component.
+
+```css
+/* app root stylesheet — add once */
+@import '@companycam/slab-tokens/css/base.css';
+@import '@companycam/slab-tokens/css/light_environment.css';
+@import '@companycam/slab-tokens/css/dark_environment.css';
+```
+
+## Core Patterns
+
+### Apply color tokens in a styled component
+
+```tsx
+import styled from 'styled-components';
+
+const ErrorText = styled.span`
+  color: var(--cc_color_utility_destroy);
+`;
+
+const Card = styled.div`
+  background-color: var(--cc_color_background_2);
+  border: var(--cc_size_border_width_s) solid var(--cc_color_border_default);
+  border-radius: var(--cc_size_border_radius_l);
+  box-shadow: 0 var(--cc_size_depth_2_y) var(--cc_size_depth_2_blur) var(--cc_color_depth_2);
+`;
+```
+
+### Apply spacing via ccMargin on a Slab component
+
+`ccMargin` accepts space-separated token names following CSS shorthand order (top right bottom left).
+
+```tsx
+import { Button } from '@companycam/slab-web';
+
+<Button ccMargin="m">Save</Button>         // 16px all sides
+<Button ccMargin="s m">Save</Button>       // 8px vertical, 16px horizontal
+<Button ccMargin="xl l m s">Save</Button>  // top right bottom left
+```
+
+### Apply spacing tokens in CSS
+
+```css
+.feature-section {
+  padding: var(--cc_size_spacing_l) var(--cc_size_spacing_m);
+  gap: var(--cc_size_spacing_s);
+}
+```
+
+### Apply text size tokens in a styled component
+
+For typography, prefer the `Text` component. When a custom element needs a size token:
+
+```tsx
+import styled from 'styled-components';
+
+const MetaLabel = styled.span`
+  font-size: var(--cc_size_text_xs); /* 12px */
+  color: var(--cc_color_text_subtle);
+`;
+
+const SectionTitle = styled.h2`
+  font-size: var(--cc_size_text_xl); /* 24px */
+  color: var(--cc_color_text_default);
+`;
+```
+
+## Token Reference
+
+### Color tokens (`--cc_color_*`)
+
+| Category     | Key tokens                                                                                                                       |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| `brand`      | `brand_primary` (#0967D2), `brand_secondary` (#142334), `brand_accent` (#FFD000)                                                 |
+| `utility`    | `utility_destroy`, `utility_success`, `utility_caution`, `utility_info`, `utility_assigned`, `utility_add_on`, `utility_upgrade` |
+| `background` | `background_1` (page default), `background_2` (sidebars/callouts), `background_3` (chips/avatars), `background_backdrop`         |
+| `text`       | `text_default`, `text_subtle`, `text_nonessential`                                                                               |
+| `button`     | `button_background_primary/secondary/subtle/destroy/success`, `button_text_primary/secondary/subtle/destroy/success`             |
+| `link`       | `link_primary`, `link_secondary`, `link_subtle`                                                                                  |
+| `border`     | `border_default`, `border_input_inactive`, `border_input_active`                                                                 |
+| `depth`      | `depth_1/2/3` (shadow color); pair with `--cc_size_depth_{n}_blur` and `--cc_size_depth_{n}_y`                                   |
+| `label`      | `label_green/blue/purple/navy/yellow/orange/red/light-gray/dark-gray`                                                            |
+| `collab`     | `collab_purple/orange/green/blue/red/yellow/navy/plum/magenta/brown/owner`                                                       |
+
+Note: New primitive color scales (`--cc_color_blue_500`, `--cc_color_slate_200`, etc.) exist in base.css but are not used by the Slab web component library. Use the semantic categories above. Only reach for primitives if a design explicitly specifies one.
+
+### Spacing tokens (`--cc_size_spacing_*`)
+
+`xxs` 2px · `xs` 4px · `s` 8px · `m` 16px · `l` 24px · `xl` 32px · `xxl` 48px
+
+### Text size tokens (`--cc_size_text_*`)
+
+`xxs` 10px · `xs` 12px · `s` 14px · `m` 16px · `l` 20px · `xl` 24px · `xxl` 32px · `xxxl` 42px
+
+### Border tokens
+
+- Radius: `--cc_size_border_radius_s/m/l/xl/xxl/pill` (2/4/8/16/24/1000px)
+- Width: `--cc_size_border_width_s/m/l/xl` (1/2/4/8px)
+
+### Depth (shadow) tokens
+
+```css
+box-shadow: 0 var(--cc_size_depth_2_y) var(--cc_size_depth_2_blur) var(--cc_color_depth_2);
+/* depth 1: tooltips · depth 2: cards/popovers · depth 3: modals/floating bars */
+```
+
+## Common Mistakes
+
+### HIGH Missing slab-tokens CSS imports — all variables undefined
+
+Wrong:
+
+```css
+/* no CSS imports — all --cc_* variables resolve to empty string */
+```
+
+Correct:
+
+```css
+/* once in app root stylesheet */
+@import '@companycam/slab-tokens/css/base.css';
+@import '@companycam/slab-tokens/css/light_environment.css';
+@import '@companycam/slab-tokens/css/dark_environment.css';
+```
+
+Without all three imports every `--cc_*` variable is undefined, components render unstyled, and no error is thrown. These are app-level — add once, not per component.
+
+Source: `CompanyCam/slab:packages/slab-tokens/dist/css/`
+
+### HIGH Constructing CSS variable names with wrong separators or structure
+
+Wrong:
+
+```css
+color: var(--cc-color-primary); /* hyphens instead of underscores */
+background: var(--cc_color_action_primary); /* "action" category doesn't exist */
+border: var(--cc_color_border); /* missing subcategory */
+```
+
+Correct:
+
+```css
+color: var(--cc_color_button_background_primary);
+background: var(--cc_color_background_1);
+border-color: var(--cc_color_border_default);
+```
+
+All Slab CSS variables use underscores and follow the full `--cc_{type}_{category}_{subcategory}` path. A plausible-but-wrong name resolves to empty silently.
+
+Source: `CompanyCam/slab:packages/slab-tokens/dist/css/base.css`
+
+### HIGH Using hardcoded hex or rgb values instead of CSS variables
+
+Wrong:
+
+```tsx
+const ErrorText = styled.span`
+  color: #ef4e4e;
+`;
+```
+
+Correct:
+
+```tsx
+const ErrorText = styled.span`
+  color: var(--cc_color_utility_destroy);
+`;
+```
+
+Hardcoded values don't respond to dark mode (light/dark env CSS files swap variable values automatically) and drift when the design system updates.
+
+Source: `CompanyCam/slab:packages/slab-tokens/src/tokens/colors/color.json`
+
+### MEDIUM Passing px values to ccMargin instead of token strings
+
+Wrong:
+
+```tsx
+<Button ccMargin="16px 8px">Save</Button>
+```
+
+Correct:
+
+```tsx
+<Button ccMargin="m s">Save</Button>
+```
+
+`ccMargin` passes values through `spacingTokensToCSS()` which maps token names to CSS variable calls. Passing `16px` produces invalid CSS output silently. Valid values: `xxs xs s m l xl xxl`.
+
+Source: `CompanyCam/slab:packages/slab-web/src/lib/shared/styles.ts`
+
+### MEDIUM Using inline style with px instead of ccMargin or CSS variables
+
+Wrong:
+
+```tsx
+<Button style={{ margin: '16px' }}>Save</Button>
+```
+
+Correct:
+
+```tsx
+<Button ccMargin="m">Save</Button>
+```
+
+Inline style bypasses the token system entirely and does not adapt to dark mode. Use `ccMargin` on Slab components and CSS variables in custom styled-components.
+
+Source: `CompanyCam/slab:packages/slab-web/src/lib/shared/styles.ts`