From 1e4ccdb57b83e654d9d0fe9f8e1e81ce23c6da21 Mon Sep 17 00:00:00 2001 From: Josemar Luedke Date: Mon, 8 Dec 2025 18:54:17 -0800 Subject: [PATCH 1/3] docs: rework design system documentation and configure tailwind-merge MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - **Design system documentation improvements:** - Removed excessive examples that didn't match actual components - Removed sections showing standard Tailwind features - Streamlined icon sizes, borders, and elevation docs - **Typography system updates:** - Changed CSS variables from `--font-family-*` to `--font-*` - Updated typography docs to show new two-part pattern (font-family + text-style) - Documented that composite text styles don't include font-family - Fixed all documentation references to use shorter variable names - **Tailwind-merge configuration:** - Added `COMMON_UNITS` constant for shared size tokens across design system - Configured icon sizes to conflict with w/h/size utilities - Configured text style composites to conflict with font-size utilities - Added configuration for borders, radius, elevation, and opacity tokens - **Icon component updates:** - Added semantic size-icon-* defaults to all icon components - Allows size overrides while maintaining consistent defaults - Small icons default to size-icon-sm, medium to size-icon-md, large to size-icon-lg 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- docs/theming/configuration/css-variables.md | 18 +- docs/theming/configuration/customization.md | 18 +- docs/theming/design-tokens/borders.md | 97 ---- docs/theming/design-tokens/elevation.md | 156 +---- docs/theming/design-tokens/icons.md | 255 ++++----- docs/theming/design-tokens/typography.md | 184 +++--- packages/theme/src/styles/typography.css | 594 +++++++------------- packages/theme/src/tw.ts | 59 +- site/app/components/icons.gts | 50 +- 9 files changed, 555 insertions(+), 876 deletions(-) diff --git a/docs/theming/configuration/css-variables.md b/docs/theming/configuration/css-variables.md index 34e94f8bf..e2202113f 100644 --- a/docs/theming/configuration/css-variables.md +++ b/docs/theming/configuration/css-variables.md @@ -43,12 +43,12 @@ Variables defined in `:root` or theme-specific selectors are for component-speci ```css @theme { - --font-family-header: system-ui, sans-serif; - --font-family-body: system-ui, sans-serif; - --font-family-code: 'Courier New', monospace; - --font-family-label: system-ui, sans-serif; - --font-family-caption: system-ui, sans-serif; - --font-family-marquee: system-ui, sans-serif; + --font-header: system-ui, sans-serif; + --font-body: system-ui, sans-serif; + --font-code: 'Courier New', monospace; + --font-label: system-ui, sans-serif; + --font-caption: system-ui, sans-serif; + --font-marquee: system-ui, sans-serif; } ``` @@ -303,9 +303,9 @@ Or per-theme: } @theme { - --font-family-header: 'Inter', system-ui, sans-serif; - --font-family-body: 'Inter', system-ui, sans-serif; - --font-family-label: 'Inter', system-ui, sans-serif; + --font-header: 'Inter', system-ui, sans-serif; + --font-body: 'Inter', system-ui, sans-serif; + --font-label: 'Inter', system-ui, sans-serif; } ``` diff --git a/docs/theming/configuration/customization.md b/docs/theming/configuration/customization.md index a0d7521bc..907611907 100644 --- a/docs/theming/configuration/customization.md +++ b/docs/theming/configuration/customization.md @@ -116,10 +116,10 @@ Override font families for different text categories: } @theme { - --font-family-header: 'Inter', system-ui, sans-serif; - --font-family-body: 'Inter', system-ui, sans-serif; - --font-family-label: 'Inter', system-ui, sans-serif; - --font-family-code: 'JetBrains Mono', monospace; + --font-header: 'Inter', system-ui, sans-serif; + --font-body: 'Inter', system-ui, sans-serif; + --font-label: 'Inter', system-ui, sans-serif; + --font-code: 'JetBrains Mono', monospace; } ``` @@ -130,12 +130,12 @@ Use different fonts for light and dark themes: ```css .light, .dark .theme-inverse { - --font-family-body: 'Inter', system-ui, sans-serif; + --font-body: 'Inter', system-ui, sans-serif; } .dark, .light .theme-inverse { - --font-family-body: 'Geist', system-ui, sans-serif; + --font-body: 'Geist', system-ui, sans-serif; } ``` @@ -368,9 +368,9 @@ module.exports = frontile({ @theme { /* Typography */ - --font-family-header: 'Poppins', system-ui, sans-serif; - --font-family-body: 'Poppins', system-ui, sans-serif; - --font-family-label: 'Poppins', system-ui, sans-serif; + --font-header: 'Poppins', system-ui, sans-serif; + --font-body: 'Poppins', system-ui, sans-serif; + --font-label: 'Poppins', system-ui, sans-serif; /* Rounded design */ --radius: 12px; diff --git a/docs/theming/design-tokens/borders.md b/docs/theming/design-tokens/borders.md index 685c0482a..d5bca013e 100644 --- a/docs/theming/design-tokens/borders.md +++ b/docs/theming/design-tokens/borders.md @@ -120,55 +120,6 @@ Control corner rounding with radius tokens that range from sharp edges to fully | Default (Custom) | `rounded-default` | Custom default radius value, soft friendly corners | | Pill | `rounded-pill` | Pills, badges, fully rounded buttons | -### Border Radius Examples - -```gts preview - -``` - ## Combining Borders and Radius Use border widths and radius together to create various UI patterns: @@ -197,54 +148,6 @@ Use border widths and radius together to create various UI patterns: ``` -## Directional Border Utilities - -Tailwind's directional utilities work with Frontile's border width tokens: - -```gts preview - -``` - -## Directional Border Radius - -Apply radius to specific corners: - -```gts preview - -``` - ## Best Practices ### Maintain Consistency diff --git a/docs/theming/design-tokens/elevation.md b/docs/theming/design-tokens/elevation.md index 653eb4679..9024c43b7 100644 --- a/docs/theming/design-tokens/elevation.md +++ b/docs/theming/design-tokens/elevation.md @@ -21,34 +21,34 @@ Higher elevations indicate elements that are more prominent or interactive, such @@ -74,8 +74,8 @@ Higher elevations indicate elements that are more prominent or interactive, such
{{! Basic card with level 2 elevation }}
-

Product Card

-

+

Product Card

+

Standard card with level 2 elevation provides subtle depth.

- -``` - -### Dropdown Menus - -```gts preview - -``` - -### Modal Dialog - -```gts preview - -``` - -### Alert Notifications - -```gts preview - -``` - -## Combining with Other Tokens - -### Elevation with Border Radius - -Pair elevation with border radius for polished UI: - -```gts preview - -``` - -### Elevation with Colors - -Use semantic colors with elevation: - -```gts preview - diff --git a/docs/theming/design-tokens/icons.md b/docs/theming/design-tokens/icons.md index 1fb412062..70f36ae34 100644 --- a/docs/theming/design-tokens/icons.md +++ b/docs/theming/design-tokens/icons.md @@ -77,59 +77,148 @@ Apply icon sizes using the `size-icon-*` utilities, which set both width and hei | Kilo | `size-icon-kilo` | Very large decorative icons | | Mega | `size-icon-mega` | Largest decorative icons | +## All Icon Sizes + +Here are all available icon sizes with visual examples: + +```gts preview +import { CheckIcon } from 'site/components/icons'; + + +``` + ## Pairing with Typography Icon sizes are designed to pair harmoniously with text styles. Use these recommended pairings for visual alignment: ```gts preview +import { CheckIcon, ViewIcon, StarIcon } from 'site/components/icons'; + @@ -147,100 +236,6 @@ Icon sizes are designed to pair harmoniously with text styles. Use these recomme | `text-header-lg` | `size-icon-lg` or `size-icon-xl` | | `text-header-xl` | `size-icon-xl` or `size-icon-2xl` | -## Common Use Cases - -### Buttons with Icons - -```gts preview - -``` - -### List Items with Icons - -```gts preview - -``` - -### Input Fields with Icons - -```gts preview - -``` - ## Customization Override icon sizes using CSS variables in your `@theme` block: diff --git a/docs/theming/design-tokens/typography.md b/docs/theming/design-tokens/typography.md index e45fcc403..fe8806cb6 100644 --- a/docs/theming/design-tokens/typography.md +++ b/docs/theming/design-tokens/typography.md @@ -28,10 +28,10 @@ Large, bold display text for hero sections and prominent headings. ```gts preview ``` @@ -46,16 +46,16 @@ Semantic headings for content hierarchy with bold weight and condensed letter sp ```gts preview ``` @@ -70,34 +70,34 @@ Standard body text with spacious line height optimized for readability. ```gts preview