Skip to content

docs: rework design system documentation and configure tailwind-merge #430

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
josemarluedke merged 3 commits into from
Dec 9, 2025
Merged

docs: rework design system documentation and configure tailwind-merge #430

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1e4ccdb
docs: rework design system documentation and configure tailwind-merge
josemarluedke Dec 9, 2025
7048e1e
fix(theme): configure tailwind-merge and tailwind-variants with custo…
josemarluedke Dec 9, 2025
cfcea65
refactor(theme): extract shared twMergeConfig to eliminate duplication
josemarluedke Dec 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions docs/theming/configuration/css-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
```

Expand Down Expand Up @@ -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;
}
```

Expand Down
18 changes: 9 additions & 9 deletions docs/theming/configuration/customization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
```

Expand All @@ -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;
}
```

Expand Down Expand Up @@ -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;
Expand Down
97 changes: 0 additions & 97 deletions docs/theming/design-tokens/borders.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
<template>
<div class='space-y-6'>
{{! Button group with different radii }}
<div class='flex gap-3 flex-wrap'>
<button class='bg-brand-medium text-on-brand-medium px-4 py-2 rounded-sm hover:bg-brand-soft'>
Sharp (SM)
</button>
<button class='bg-brand-medium text-on-brand-medium px-4 py-2 rounded hover:bg-brand-soft'>
Default
</button>
<button class='bg-brand-medium text-on-brand-medium px-4 py-2 rounded-xl hover:bg-brand-soft'>
Soft (XL)
</button>
<button class='bg-brand-medium text-on-brand-medium px-6 py-2 rounded-pill hover:bg-brand-soft'>
Pill
</button>
</div>

{{! Cards with different radii }}
<div class='grid md:grid-cols-2 gap-4'>
<div class='border border-neutral-medium rounded-md p-6'>
<h3 class='text-header-sm mb-2'>Standard Card</h3>
<p class='text-body-sm text-neutral-soft'>Uses rounded-md for subtle corners</p>
</div>
<div class='border border-neutral-medium rounded-2xl p-6'>
<h3 class='text-header-sm mb-2'>Feature Card</h3>
<p class='text-body-sm text-neutral-soft'>Uses rounded-2xl for prominent display</p>
</div>
</div>

{{! Badges and pills }}
<div class='flex gap-3 flex-wrap items-center'>
<span class='bg-neutral-subtle text-neutral-strong px-3 py-1 rounded text-label-xs'>
Rounded Badge
</span>
<span class='bg-success-subtle text-success-strong px-3 py-1 rounded-pill text-label-xs'>
Pill Badge
</span>
<span class='bg-brand-medium text-on-brand-medium px-3 py-1 rounded-xl text-label-xs'>
Soft Badge
</span>
</div>
</div>
</template>
```

## Combining Borders and Radius

Use border widths and radius together to create various UI patterns:
Expand Down Expand Up @@ -197,54 +148,6 @@ Use border widths and radius together to create various UI patterns:
</template>
```

## Directional Border Utilities

Tailwind's directional utilities work with Frontile's border width tokens:

```gts preview
<template>
<div class='space-y-4'>
{{! Top border only }}
<div class='border-t-heavy border-brand-medium p-4 bg-background'>
<p class='text-body-sm'>Top border (heavy)</p>
</div>

{{! Left border accent }}
<div class='border-l-aggressive border-success-medium p-4 bg-background'>
<p class='text-body-sm'>Left border accent (aggressive)</p>
</div>

{{! Bottom divider }}
<div class='border-b-thin border-neutral-medium p-4 bg-background'>
<p class='text-body-sm'>Bottom divider (thin)</p>
</div>
</div>
</template>
```

## Directional Border Radius

Apply radius to specific corners:

```gts preview
<template>
<div class='grid md:grid-cols-3 gap-4'>
<div class='bg-brand-subtle p-6 rounded-t-xl'>
<p class='text-body-sm'>Top rounded</p>
<code class='text-code-sm'>rounded-t-xl</code>
</div>
<div class='bg-brand-subtle p-6 rounded-b-xl'>
<p class='text-body-sm'>Bottom rounded</p>
<code class='text-code-sm'>rounded-b-xl</code>
</div>
<div class='bg-brand-subtle p-6 rounded-l-xl'>
<p class='text-body-sm'>Left rounded</p>
<code class='text-code-sm'>rounded-l-xl</code>
</div>
</div>
</template>
```

## Best Practices

### Maintain Consistency
Expand Down
156 changes: 24 additions & 132 deletions docs/theming/design-tokens/elevation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,34 +21,34 @@ Higher elevations indicate elements that are more prominent or interactive, such
<template>
<div class='grid grid-cols-2 md:grid-cols-3 gap-8 bg-surface-solid-1 p-8'>
<div class='shadow-elevation-0 bg-background p-6 rounded'>
<h3 class='text-header-sm mb-2'>Level 0</h3>
<p class='text-body-sm text-neutral-soft'>No shadow</p>
<p class='text-caption-sm text-neutral-soft mt-2'>Flat surface</p>
<h3 class='mb-2'>Level 0</h3>
<p class='text-neutral-soft'>No shadow</p>
<p class='text-neutral-soft text-sm mt-2'>Flat surface</p>
</div>
<div class='shadow-elevation-1 bg-background p-6 rounded'>
<h3 class='text-header-sm mb-2'>Level 1</h3>
<p class='text-body-sm text-neutral-soft'>Subtle lift</p>
<p class='text-caption-sm text-neutral-soft mt-2'>Hover states</p>
<h3 class='mb-2'>Level 1</h3>
<p class='text-neutral-soft'>Subtle lift</p>
<p class='text-neutral-soft text-sm mt-2'>Hover states</p>
</div>
<div class='shadow-elevation-2 bg-background p-6 rounded'>
<h3 class='text-header-sm mb-2'>Level 2</h3>
<p class='text-body-sm text-neutral-soft'>Raised surface</p>
<p class='text-caption-sm text-neutral-soft mt-2'>Cards, panels</p>
<h3 class='mb-2'>Level 2</h3>
<p class='text-neutral-soft'>Raised surface</p>
<p class='text-neutral-soft text-sm mt-2'>Cards, panels</p>
</div>
<div class='shadow-elevation-3 bg-background p-6 rounded'>
<h3 class='text-header-sm mb-2'>Level 3</h3>
<p class='text-body-sm text-neutral-soft'>Floating element</p>
<p class='text-caption-sm text-neutral-soft mt-2'>Dropdowns</p>
<h3 class='mb-2'>Level 3</h3>
<p class='text-neutral-soft'>Floating element</p>
<p class='text-neutral-soft text-sm mt-2'>Dropdowns</p>
</div>
<div class='shadow-elevation-4 bg-background p-6 rounded'>
<h3 class='text-header-sm mb-2'>Level 4</h3>
<p class='text-body-sm text-neutral-soft'>Elevated overlay</p>
<p class='text-caption-sm text-neutral-soft mt-2'>Modals, dialogs</p>
<h3 class='mb-2'>Level 4</h3>
<p class='text-neutral-soft'>Elevated overlay</p>
<p class='text-neutral-soft text-sm mt-2'>Modals, dialogs</p>
</div>
<div class='shadow-elevation-5 bg-background p-6 rounded'>
<h3 class='text-header-sm mb-2'>Level 5</h3>
<p class='text-body-sm text-neutral-soft'>Maximum depth</p>
<p class='text-caption-sm text-neutral-soft mt-2'>Top layer</p>
<h3 class='mb-2'>Level 5</h3>
<p class='text-neutral-soft'>Maximum depth</p>
<p class='text-neutral-soft text-sm mt-2'>Top layer</p>
</div>
</div>
</template>
Expand All @@ -74,8 +74,8 @@ Higher elevations indicate elements that are more prominent or interactive, such
<div class='grid md:grid-cols-2 gap-6'>
{{! Basic card with level 2 elevation }}
<div class='shadow-elevation-2 bg-background rounded-xl p-6'>
<h3 class='text-header-md mb-3'>Product Card</h3>
<p class='text-body-sm text-neutral-soft mb-4'>
<h3 class='mb-3'>Product Card</h3>
<p class='text-neutral-soft mb-4'>
Standard card with level 2 elevation provides subtle depth.
</p>
<button class='bg-brand-medium text-on-brand-medium px-4 py-2 rounded hover:bg-brand-soft'>
Expand All @@ -85,8 +85,8 @@ Higher elevations indicate elements that are more prominent or interactive, such

{{! Feature card with no shadow }}
<div class='shadow-elevation-0 border border-neutral-medium bg-background rounded-xl p-6'>
<h3 class='text-header-md mb-3'>Flat Card</h3>
<p class='text-body-sm text-neutral-soft mb-4'>
<h3 class='mb-3'>Flat Card</h3>
<p class='text-neutral-soft mb-4'>
Uses border instead of shadow for a flatter appearance.
</p>
<button class='border border-brand-medium text-brand-medium px-4 py-2 rounded hover:bg-brand-subtle'>
Expand All @@ -113,116 +113,8 @@ Higher elevations indicate elements that are more prominent or interactive, such
<div
class='bg-background rounded-xl p-6 shadow-elevation-1 hover:shadow-elevation-2 transition-shadow cursor-pointer'
>
<h4 class='text-header-sm mb-2'>Interactive Card</h4>
<p class='text-body-sm text-neutral-soft'>Elevation increases on hover</p>
</div>
</div>
</template>
```

### Dropdown Menus

```gts preview
<template>
<div class='relative inline-block'>
<button class='bg-brand-medium text-on-brand-medium px-4 py-2 rounded'>
Open Menu
</button>
{{! Dropdown with level 3 elevation }}
<div
class='absolute mt-2 w-56 shadow-elevation-3 bg-background rounded-lg overflow-hidden'
>
<a href='#' class='block px-4 py-3 hover:bg-neutral-subtle text-body-sm'>Menu Item 1</a>
<a href='#' class='block px-4 py-3 hover:bg-neutral-subtle text-body-sm'>Menu Item 2</a>
<a href='#' class='block px-4 py-3 hover:bg-neutral-subtle text-body-sm'>Menu Item 3</a>
</div>
</div>
</template>
```

### Modal Dialog

```gts preview
<template>
<div class='relative h-64 flex items-center justify-center bg-surface-solid-1 rounded-lg'>
{{! Modal with level 4 elevation }}
<div class='shadow-elevation-4 bg-background rounded-xl p-8 max-w-md'>
<h3 class='text-header-lg mb-4'>Confirm Action</h3>
<p class='text-body-md text-neutral-soft mb-6'>
Are you sure you want to proceed with this action?
</p>
<div class='flex gap-3 justify-end'>
<button class='border border-neutral-medium px-4 py-2 rounded hover:bg-neutral-subtle'>
Cancel
</button>
<button class='bg-brand-medium text-on-brand-medium px-4 py-2 rounded hover:bg-brand-soft'>
Confirm
</button>
</div>
</div>
</div>
</template>
```

### Alert Notifications

```gts preview
<template>
<div class='space-y-4'>
{{! Standard alert with level 2 elevation }}
<div class='shadow-elevation-2 bg-background border-l-aggressive border-brand-medium rounded p-4'>
<h4 class='text-label-md mb-1'>Information</h4>
<p class='text-body-sm text-neutral-soft'>Standard notification with moderate elevation.</p>
</div>

{{! Critical alert with level 5 elevation }}
<div class='shadow-elevation-5 bg-danger-medium text-on-danger-medium rounded p-4'>
<h4 class='text-label-md mb-1'>Critical Alert</h4>
<p class='text-body-sm'>Maximum elevation draws immediate attention.</p>
</div>
</div>
</template>
```

## Combining with Other Tokens

### Elevation with Border Radius

Pair elevation with border radius for polished UI:

```gts preview
<template>
<div class='grid md:grid-cols-3 gap-4'>
<div class='shadow-elevation-2 rounded-sm bg-background p-4'>
<p class='text-body-sm'>Sharp corners</p>
<code class='text-code-sm'>rounded-sm</code>
</div>
<div class='shadow-elevation-2 rounded-xl bg-background p-4'>
<p class='text-body-sm'>Soft corners</p>
<code class='text-code-sm'>rounded-xl</code>
</div>
<div class='shadow-elevation-2 rounded-2xl bg-background p-4'>
<p class='text-body-sm'>Very soft</p>
<code class='text-code-sm'>rounded-2xl</code>
</div>
</div>
</template>
```

### Elevation with Colors

Use semantic colors with elevation:

```gts preview
<template>
<div class='grid md:grid-cols-2 gap-4'>
<div class='shadow-elevation-2 bg-success-subtle border border-success-soft rounded-xl p-4'>
<h4 class='text-label-md text-success-strong mb-2'>Success</h4>
<p class='text-body-sm text-success-strong'>Elevated success message</p>
</div>
<div class='shadow-elevation-3 bg-warning-medium text-on-warning-medium rounded-xl p-4'>
<h4 class='text-label-md mb-2'>Warning</h4>
<p class='text-body-sm'>High-elevation warning</p>
<h4 class='mb-2'>Interactive Card</h4>
<p class='text-neutral-soft'>Elevation increases on hover</p>
</div>
</div>
</template>
Expand Down
Loading
Loading