@tydavidson/design-system 1.1.6 → 1.1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/README.md +59 -1
  2. package/docs/component-colors.ts +94 -0
  3. package/docs/component-specific-colors.md +253 -0
  4. package/docs/setup-guide.md +276 -0
  5. package/docs/theme-usage.md +668 -0
  6. package/docs/troubleshooting.md +130 -0
  7. package/package.json +3 -2
package/README.md CHANGED
@@ -1,4 +1,62 @@
1
- # component-library
1
+ # Float Design System
2
+
3
+ A modern React design system with comprehensive theming, component library, and email components.
4
+
5
+ ## Quick Start
6
+
7
+ ```bash
8
+ npm install @tydavidson/design-system
9
+ ```
10
+
11
+ ## Documentation
12
+
13
+ 📚 **Setup Guide**: [docs/setup-guide.md](docs/setup-guide.md) - Complete installation and configuration guide
14
+
15
+ 🔧 **Troubleshooting**: [docs/troubleshooting.md](docs/troubleshooting.md) - Quick fixes for common issues
16
+
17
+ 🎨 **Theme Usage**: [docs/theme-usage.md](docs/theme-usage.md) - Detailed theme system documentation
18
+
19
+ ## Features
20
+
21
+ - ✅ **Modern React Components** - Built with TypeScript and React 18+
22
+ - ✅ **Theme System** - Light/dark mode with CSS variables
23
+ - ✅ **Next.js Compatible** - Works with App Router and Pages Router
24
+ - ✅ **Email Components** - Responsive email templates
25
+ - ✅ **Tabler Icons** - Consistent icon library
26
+ - ✅ **Tailwind CSS** - Utility-first styling
27
+ - ✅ **TypeScript** - Full type safety
28
+
29
+ ## Basic Usage
30
+
31
+ ```tsx
32
+ import { ThemeProvider, useTheme, ThemeToggle } from '@tydavidson/design-system/themes';
33
+ import { Button, Card, CardContent, CardHeader, CardTitle } from '@tydavidson/design-system';
34
+ import '@tydavidson/design-system/themes/theme.css';
35
+
36
+ function App() {
37
+ return (
38
+ <ThemeProvider>
39
+ <Card>
40
+ <CardHeader>
41
+ <CardTitle>Welcome</CardTitle>
42
+ </CardHeader>
43
+ <CardContent>
44
+ <Button>Get Started</Button>
45
+ <ThemeToggle />
46
+ </CardContent>
47
+ </Card>
48
+ </ThemeProvider>
49
+ );
50
+ }
51
+ ```
52
+
53
+ ## Required Dependencies
54
+
55
+ ```bash
56
+ npm install react react-dom next-themes @tabler/icons-react
57
+ ```
58
+
59
+ ---
2
60
 
3
61
  ## Development Commands
4
62
 
package/docs/component-colors.ts ADDED
@@ -0,0 +1,94 @@
1
+
2
+ // export const componentColorsComponentsAppStoreBadgesAppStoreBadgeBorder = '#a6a6a6'
3
+ // export const componentColorsComponentsApplicationNavigationNavItemButtonIconFg = 'var(--colors-gray-light-mode-500)'
4
+ // export const componentColorsComponentsApplicationNavigationNavItemButtonIconFg_active = 'var(--colors-gray-light-mode-700)'
5
+ // export const componentColorsComponentsApplicationNavigationNavItemIconFg = 'var(--colors-gray-light-mode-500)'
6
+ // export const componentColorsComponentsApplicationNavigationNavItemIconFg_active = 'var(--colors-gray-light-mode-500)'
7
+ // export const componentColorsComponentsAvatarsAvatarBg = 'var(--colors-gray-light-mode-100)'
8
+ // export const componentColorsComponentsAvatarsAvatarContrastBorder = '#00000014'
9
+ // export const componentColorsComponentsAvatarsAvatarFocusBorder = '#98a2b324'
10
+ // export const componentColorsComponentsAvatarsAvatarProfilePhotoBorder = 'var(--colors-base-white)'
11
+ // export const componentColorsComponentsBreadcrumbsBreadcrumbBg_hover = 'var(--colors-gray-light-mode-50)'
12
+ // export const componentColorsComponentsBreadcrumbsBreadcrumbBrandBg_hover = 'var(--colors-brand-50)'
13
+ // export const componentColorsComponentsBreadcrumbsBreadcrumbBrandFg_hover = 'var(--colors-brand-700)'
14
+ // export const componentColorsComponentsBreadcrumbsBreadcrumbBrandIconFg_hover = 'var(--colors-brand-700)'
15
+ // export const componentColorsComponentsBreadcrumbsBreadcrumbFg = 'var(--colors-gray-light-mode-600)'
16
+ // export const componentColorsComponentsBreadcrumbsBreadcrumbFg_hover = 'var(--colors-gray-light-mode-700)'
17
+ // export const componentColorsComponentsBreadcrumbsBreadcrumbIconFg = 'var(--colors-gray-light-mode-500)'
18
+ // export const componentColorsComponentsBreadcrumbsBreadcrumbIconFg_hover = 'var(--colors-gray-light-mode-700)'
19
+ export const componentColorsComponentsButtonsPrimaryButtonPrimaryBg = 'var(--colors-brand-700)'
20
+ export const componentColorsComponentsButtonsPrimaryButtonPrimaryBg_hover = 'var(--colors-brand-800)'
21
+ export const componentColorsComponentsButtonsPrimaryButtonPrimaryBorder = 'var(--colors-brand-700)'
22
+ export const componentColorsComponentsButtonsPrimaryButtonPrimaryBorder_hover = 'var(--colors-brand-800)'
23
+ export const componentColorsComponentsButtonsPrimaryButtonPrimaryFg = 'var(--colors-base-white)'
24
+ export const componentColorsComponentsButtonsPrimaryButtonPrimaryFg_hover = 'var(--colors-base-white)'
25
+ export const componentColorsComponentsButtonsPrimaryErrorButtonPrimaryErrorBg = 'var(--colors-error-600)'
26
+ export const componentColorsComponentsButtonsPrimaryErrorButtonPrimaryErrorBg_hover = 'var(--colors-error-700)'
27
+ export const componentColorsComponentsButtonsPrimaryErrorButtonPrimaryErrorBorder = 'var(--colors-error-600)'
28
+ export const componentColorsComponentsButtonsPrimaryErrorButtonPrimaryErrorBorder_hover = 'var(--colors-error-700)'
29
+ export const componentColorsComponentsButtonsPrimaryErrorButtonPrimaryErrorFg = 'var(--colors-base-white)'
30
+ export const componentColorsComponentsButtonsPrimaryErrorButtonPrimaryErrorFg_hover = 'var(--colors-base-white)'
31
+ export const componentColorsComponentsButtonsSecondaryButtonSecondaryBg = 'var(--colors-base-white)'
32
+ export const componentColorsComponentsButtonsSecondaryButtonSecondaryBg_hover = 'var(--colors-gray-light-mode-50)'
33
+ export const componentColorsComponentsButtonsSecondaryButtonSecondaryBorder = 'var(--colors-gray-light-mode-300)'
34
+ export const componentColorsComponentsButtonsSecondaryButtonSecondaryBorder_hover = 'var(--colors-gray-light-mode-300)'
35
+ export const componentColorsComponentsButtonsSecondaryButtonSecondaryFg = 'var(--colors-gray-light-mode-700)'
36
+ export const componentColorsComponentsButtonsSecondaryButtonSecondaryFg_hover = 'var(--colors-gray-light-mode-800)'
37
+ export const componentColorsComponentsButtonsSecondaryColorButtonSecondaryColorBg = 'var(--colors-base-white)'
38
+ export const componentColorsComponentsButtonsSecondaryColorButtonSecondaryColorBg_hover = 'var(--colors-brand-50)'
39
+ export const componentColorsComponentsButtonsSecondaryColorButtonSecondaryColorBorder = 'var(--colors-brand-300)'
40
+ export const componentColorsComponentsButtonsSecondaryColorButtonSecondaryColorBorder_hover = 'var(--colors-brand-300)'
41
+ export const componentColorsComponentsButtonsSecondaryColorButtonSecondaryColorFg = 'var(--colors-brand-600)'
42
+ export const componentColorsComponentsButtonsSecondaryColorButtonSecondaryColorFg_hover = 'var(--colors-brand-700)'
43
+ export const componentColorsComponentsButtonsSecondaryErrorButtonSecondaryErrorBg = 'var(--colors-base-white)'
44
+ export const componentColorsComponentsButtonsSecondaryErrorButtonSecondaryErrorBg_hover = 'var(--colors-error-50)'
45
+ export const componentColorsComponentsButtonsSecondaryErrorButtonSecondaryErrorBorder = 'var(--colors-error-300)'
46
+ export const componentColorsComponentsButtonsSecondaryErrorButtonSecondaryErrorBorder_hover = 'var(--colors-error-300)'
47
+ export const componentColorsComponentsButtonsSecondaryErrorButtonSecondaryErrorFg = 'var(--colors-error-700)'
48
+ export const componentColorsComponentsButtonsSecondaryErrorButtonSecondaryErrorFg_hover = 'var(--colors-error-800)'
49
+ export const componentColorsComponentsButtonsTertiaryButtonTertiaryBg_hover = 'var(--colors-gray-light-mode-50)'
50
+ export const componentColorsComponentsButtonsTertiaryButtonTertiaryFg = 'var(--colors-gray-light-mode-600)'
51
+ export const componentColorsComponentsButtonsTertiaryButtonTertiaryFg_hover = 'var(--colors-gray-light-mode-700)'
52
+ export const componentColorsComponentsButtonsTertiaryColorButtonTertiaryColorBg_hover = 'var(--colors-brand-50)'
53
+ export const componentColorsComponentsButtonsTertiaryColorButtonTertiaryColorFg = 'var(--colors-brand-700)'
54
+ export const componentColorsComponentsButtonsTertiaryColorButtonTertiaryColorFg_hover = 'var(--colors-brand-800)'
55
+ export const componentColorsComponentsButtonsTertiaryErrorButtonTertiaryErrorBg_hover = 'var(--colors-error-50)'
56
+ export const componentColorsComponentsButtonsTertiaryErrorButtonTertiaryErrorFg = 'var(--colors-error-700)'
57
+ export const componentColorsComponentsButtonsTertiaryErrorButtonTertiaryErrorFg_hover = 'var(--colors-error-800)'
58
+ // export const componentColorsComponentsFootersFooterBadgeBg = 'var(--colors-success-50)'
59
+ // export const componentColorsComponentsFootersFooterBadgeBorder = 'var(--colors-success-200)'
60
+ // export const componentColorsComponentsFootersFooterBadgeFg = 'var(--colors-success-700)'
61
+ // export const componentColorsComponentsFootersFooterButtonFg = 'var(--colors-brand-200)'
62
+ // export const componentColorsComponentsFootersFooterButtonFg_hover = 'var(--colors-base-white)'
63
+ // export const componentColorsComponentsHeaderSectionsHeaderAbstract100Bg = 'var(--colors-brand-100)'
64
+ // export const componentColorsComponentsHeaderSectionsHeaderAbstract200Bg = 'var(--colors-brand-200)'
65
+ // export const componentColorsComponentsHeaderSectionsHeaderAbstract300Bg = 'var(--colors-brand-300)'
66
+ // export const componentColorsComponentsHeaderSectionsHeaderAbstract50Bg = 'var(--colors-brand-50)'
67
+ // export const componentColorsComponentsIconsFeaturedIconsDarkFeaturedIconDarkFgBrand = 'var(--colors-base-white)'
68
+ // export const componentColorsComponentsIconsFeaturedIconsDarkFeaturedIconDarkFgError = 'var(--colors-base-white)'
69
+ // export const componentColorsComponentsIconsFeaturedIconsDarkFeaturedIconDarkFgGray = 'var(--colors-base-white)'
70
+ // export const componentColorsComponentsIconsFeaturedIconsDarkFeaturedIconDarkFgSuccess = 'var(--colors-base-white)'
71
+ // export const componentColorsComponentsIconsFeaturedIconsDarkFeaturedIconDarkFgWarning = 'var(--colors-base-white)'
72
+ // export const componentColorsComponentsIconsFeaturedIconsLightFeaturedIconLightFgBrand = 'var(--colors-brand-700)'
73
+ // export const componentColorsComponentsIconsFeaturedIconsLightFeaturedIconLightFgError = 'var(--colors-error-600)'
74
+ // export const componentColorsComponentsIconsFeaturedIconsLightFeaturedIconLightFgGray = 'var(--colors-gray-light-mode-500)'
75
+ // export const componentColorsComponentsIconsFeaturedIconsLightFeaturedIconLightFgSuccess = 'var(--colors-success-600)'
76
+ // export const componentColorsComponentsIconsFeaturedIconsLightFeaturedIconLightFgWarning = 'var(--colors-warning-600)'
77
+ // export const componentColorsComponentsIconsFeaturedIconsModernFeaturedIconModernBorder = 'var(--colors-gray-light-mode-200)'
78
+ // export const componentColorsComponentsIconsIconsIconFgBrand = 'var(--colors-brand-700)'
79
+ // export const componentColorsComponentsIconsIconsIconFgBrand_onBrand = 'var(--colors-brand-200)'
80
+ // export const componentColorsComponentsIconsSocialIconsSocialIconFgAngellist = 'var(--colors-base-black)'
81
+ // export const componentColorsComponentsIconsSocialIconsSocialIconFgApple = 'var(--colors-base-black)'
82
+ // export const componentColorsComponentsIconsSocialIconsSocialIconFgGithub = 'var(--colors-base-black)'
83
+ // export const componentColorsComponentsIconsSocialIconsSocialIconFgInstagram = '#000100'
84
+ // export const componentColorsComponentsIconsSocialIconsSocialIconFgTumblr = '#001935'
85
+ // export const componentColorsComponentsIconsSocialIconsSocialIconFgX = '#242e36'
86
+ // export const componentColorsComponentsMockupsScreenMockupBorder = 'var(--colors-gray-light-mode-900)'
87
+ // export const componentColorsComponentsSlidersSliderHandleBg = 'var(--colors-base-white)'
88
+ // export const componentColorsComponentsSlidersSliderHandleBorder = 'var(--colors-brand-700)'
89
+ // export const componentColorsComponentsThumbnailThumbnailBadgeBrandFg = 'var(--colors-brand-700)'
90
+ // export const componentColorsComponentsThumbnailThumbnailBadgeSuccessFg = 'var(--colors-success-700)'
91
+ // export const componentColorsComponentsTogglesToggleButtonFg_disabled = 'var(--colors-gray-light-mode-50)'
92
+ // export const componentColorsComponentsTooltipsTooltipSupportingText = 'var(--colors-gray-light-mode-300)'
93
+ // export const componentColorsComponentsWysiwygEditorWysiwygEditorIconFg = 'var(--colors-gray-light-mode-400)'
94
+ // export const componentColorsComponentsWysiwygEditorWysiwygEditorIconFg_active = 'var(--colors-gray-light-mode-500)'
package/docs/component-specific-colors.md ADDED
@@ -0,0 +1,253 @@
1
+ # Component-Specific Color System
2
+
3
+ ## Overview
4
+
5
+ The component-specific color system is designed to provide isolated, scoped color variables for individual components while maintaining consistency with our global design system. This approach allows components to have their own semantic color variables without polluting the global namespace or creating conflicts.
6
+
7
+ ## Architecture
8
+
9
+ The system follows a layered approach:
10
+
11
+ ```
12
+ src/
13
+ ├── styles/
14
+ │ ├── components/ # Component-specific CSS files
15
+ │ │ └── button.css # Button-specific variables
16
+ │ ├── constants/ # TypeScript constants
17
+ │ │ └── button-colors.ts # Button color constants
18
+ │ └── index.css # Main CSS entry point
19
+ └── components/
20
+ └── Button.tsx # Component implementation
21
+ ```
22
+
23
+ ## Naming Convention (Updated)
24
+
25
+ ### **Current Pattern: Component-First Naming**
26
+
27
+ Component-specific variables follow this pattern:
28
+ ```
29
+ --{component}-{property}-{variant}-{state}
30
+ ```
31
+
32
+ **Examples:**
33
+ - `--button-bg-primary` (Button component, background property, primary variant)
34
+ - `--button-bg-primary-hover` (Button component, background property, primary variant, hover state)
35
+ - `--input-border-focus` (Input component, border property, focus state)
36
+ - `--dropdown-item-bg-brand-hover` (Dropdown component, item sub-component, background property, brand variant, hover state)
37
+
38
+ ### **Why This Pattern?**
39
+
40
+ 1. **Component Grouping**: All variables for a component are grouped together (e.g., `--button-*`)
41
+ 2. **Developer Experience**: Autocomplete shows all related variables when typing component name
42
+ 3. **Third-party Override**: Removes namespace conflicts, allows overriding third-party library variables
43
+ 4. **Semantic Alignment**: Matches our global semantic pattern (`--bg-primary`, `--text-secondary`)
44
+
45
+ ### **Pattern Breakdown**
46
+
47
+ | Part | Purpose | Examples |
48
+ |------|---------|----------|
49
+ | `{component}` | Component name | `button`, `input`, `dropdown`, `sidebar`, `card` |
50
+ | `{property}` | CSS property type | `bg`, `text`, `border`, `shadow`, `width` |
51
+ | `{variant}` | Semantic or style variant | `primary`, `secondary`, `brand`, `error`, `outline` |
52
+ | `{state}` | Interactive state | `hover`, `focus`, `active`, `disabled`, `checked` |
53
+
54
+ ### **Complete Examples by Component**
55
+
56
+ **Button Variables:**
57
+ ```css
58
+ --button-bg-primary
59
+ --button-bg-primary-hover
60
+ --button-bg-secondary
61
+ --button-bg-destructive
62
+ --button-text-primary
63
+ --button-text-link
64
+ --button-text-link-hover
65
+ --button-border-outline
66
+ --button-border-outline-hover
67
+ --button-icon-size-sm
68
+ ```
69
+
70
+ **Input Variables:**
71
+ ```css
72
+ --input-bg
73
+ --input-bg-disabled
74
+ --input-text
75
+ --input-text-placeholder
76
+ --input-border
77
+ --input-border-hover
78
+ --input-border-focus
79
+ --input-ring
80
+ ```
81
+
82
+ **Dropdown Variables:**
83
+ ```css
84
+ --dropdown-bg
85
+ --dropdown-text
86
+ --dropdown-border
87
+ --dropdown-item-bg-hover
88
+ --dropdown-item-text-brand-hover
89
+ --dropdown-separator-bg
90
+ ```
91
+
92
+ ### **Alignment with Global Semantic Variables**
93
+
94
+ Our component variables perfectly complement the global semantic system:
95
+
96
+ ```css
97
+ /* Global Semantic Variables */
98
+ --bg-primary, --bg-secondary, --bg-brand-primary
99
+ --text-primary, --text-error-primary
100
+ --border-primary, --border-brand
101
+
102
+ /* Component Variables (Same Pattern) */
103
+ --button-bg-primary, --button-text-primary, --button-border-primary
104
+ --input-bg, --input-text, --input-border-focus
105
+ --dropdown-bg, --dropdown-item-bg-hover
106
+ ```
107
+
108
+ ## Implementation Details
109
+
110
+ ### 1. CSS Variables (button.css)
111
+
112
+ Component-specific variables are defined at the root level:
113
+
114
+ ```css
115
+ :root {
116
+ --button-bg-primary: var(--color-brand-700);
117
+ --button-bg-primary-hover: var(--color-brand-800);
118
+ --button-text-primary: white;
119
+ --button-text-primary-hover: white;
120
+ --button-border-primary: var(--color-brand-700);
121
+ --button-border-primary-hover: var(--color-brand-800);
122
+ }
123
+
124
+ .dark {
125
+ --button-bg-primary: var(--color-brand-700);
126
+ --button-bg-primary-hover: var(--color-brand-800);
127
+ /* Dark theme overrides */
128
+ }
129
+ ```
130
+
131
+ ### 2. TypeScript Constants (button-colors.ts)
132
+
133
+ For type safety and autocompletion, we define constants:
134
+
135
+ ```typescript
136
+ export const BUTTON_COLORS = {
137
+ primary: {
138
+ bg: 'var(--button-bg-primary)',
139
+ bgHover: 'var(--button-bg-primary-hover)',
140
+ text: 'var(--button-text-primary)',
141
+ textHover: 'var(--button-text-primary-hover)',
142
+ border: 'var(--button-border-primary)',
143
+ borderHover: 'var(--button-border-primary-hover)',
144
+ },
145
+ // ... other variants
146
+ } as const;
147
+
148
+ export type ButtonVariant = keyof typeof BUTTON_COLORS;
149
+ ```
150
+
151
+ ### 3. Usage in Components
152
+
153
+ Components use these variables through Tailwind's arbitrary value syntax:
154
+
155
+ ```tsx
156
+ <button
157
+ className={cn(
158
+ 'bg-[var(--button-bg-primary)]',
159
+ 'text-[var(--button-text-primary)]',
160
+ 'border-[var(--button-border-primary)]',
161
+ 'hover:bg-[var(--button-bg-primary-hover)]',
162
+ 'hover:text-[var(--button-text-primary-hover)]'
163
+ )}
164
+ >
165
+ ```
166
+
167
+ ## Benefits
168
+
169
+ 1. **Component Grouping**: All variables for a component are logically grouped
170
+ 2. **Autocomplete Friendly**: Type `--button-` to see all button-related variables
171
+ 3. **Third-party Integration**: Can override third-party library variables with same names
172
+ 4. **Semantic Consistency**: Aligns with global design system naming patterns
173
+ 5. **Type Safety**: TypeScript constants provide type checking and autocompletion
174
+ 6. **Maintainability**: Clear organization and naming conventions
175
+ 7. **Flexibility**: Easy to modify component-specific colors without affecting global system
176
+
177
+ ## Best Practices
178
+
179
+ 1. **Consistent Naming**: Always follow the `--{component}-{property}-{variant}-{state}` pattern
180
+ 2. **Property Names**: Use consistent property names (`bg`, `text`, `border`, not `background`, `color`, `border-color`)
181
+ 3. **Semantic Variants**: Use semantic names (`primary`, `secondary`) over style names (`blue`, `large`)
182
+ 4. **Global References**: Always reference global design tokens for actual color values
183
+ 5. **Documentation**: Keep component-specific variables documented
184
+ 6. **TypeScript**: Create corresponding TypeScript constants for all CSS variables
185
+
186
+ ## Adding New Components
187
+
188
+ To add component-specific colors for a new component:
189
+
190
+ 1. Create a new CSS file in `styles/components/`
191
+ 2. Define variables following the naming convention: `--{component}-{property}-{variant}`
192
+ 3. Create corresponding TypeScript constants
193
+ 4. Import the CSS file in `globals.css`
194
+ 5. Use the variables in your component
195
+
196
+ ## Example: Adding a New Component
197
+
198
+ ```css
199
+ /* styles/components/card.css */
200
+ :root {
201
+ --card-bg-default: var(--bg-secondary);
202
+ --card-bg-subtle: var(--bg-primary);
203
+ --card-border: var(--border-tertiary);
204
+ --card-shadow: 0px 1px 2px 0px rgba(0, 0, 0, 0.05);
205
+ --card-title-text: var(--text-primary);
206
+ --card-description-text: var(--text-tertiary);
207
+ }
208
+ ```
209
+
210
+ ```typescript
211
+ // styles/constants/card-colors.ts
212
+ export const CARD_COLORS = {
213
+ default: {
214
+ bg: 'var(--card-bg-default)',
215
+ border: 'var(--card-border)',
216
+ shadow: 'var(--card-shadow)',
217
+ },
218
+ subtle: {
219
+ bg: 'var(--card-bg-subtle)',
220
+ border: 'var(--card-border)',
221
+ },
222
+ title: {
223
+ text: 'var(--card-title-text)',
224
+ },
225
+ description: {
226
+ text: 'var(--card-description-text)',
227
+ },
228
+ } as const;
229
+ ```
230
+
231
+ ## Migration Guide
232
+
233
+ When migrating from the old `--float-*` naming convention:
234
+
235
+ 1. **Identify all existing variables** used by the component
236
+ 2. **Map to new naming pattern**:
237
+ - `--float-button-primary-bg` → `--button-bg-primary`
238
+ - `--float-input-border-focus` → `--input-border-focus`
239
+ - `--float-dropdown-item-brand-bg-hover` → `--dropdown-item-bg-brand-hover`
240
+ 3. **Update CSS files** with new variable names
241
+ 4. **Update TypeScript constants** to reference new variables
242
+ 5. **Update component usage** to use new variable names
243
+ 6. **Remove old variables** once migration is complete
244
+
245
+ ## Troubleshooting
246
+
247
+ Common issues and solutions:
248
+
249
+ 1. **Variables not applying**: Ensure variables are defined in `:root` scope, not component-scoped classes
250
+ 2. **Type errors**: Check that TypeScript constants are properly exported and imported
251
+ 3. **Missing variables**: Verify that all needed variables are defined following the naming pattern
252
+ 4. **Inconsistent colors**: Ensure variables reference the correct global design tokens
253
+ 5. **Autocomplete not working**: Verify variable names follow the exact pattern `--{component}-{property}-{variant}`
package/docs/setup-guide.md ADDED
@@ -0,0 +1,276 @@
1
+ # Design System Setup Guide
2
+
3
+ This guide helps you set up the Float Design System in your project and avoid common integration issues.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install @tydavidson/design-system
9
+ ```
10
+
11
+ ## Required Dependencies
12
+
13
+ The design system requires these peer dependencies (only Tabler icons are used):
14
+
15
+ ```bash
16
+ npm install react react-dom next-themes @tabler/icons-react
17
+ ```
18
+
19
+ ## CSS Setup
20
+
21
+ ### 1. Import Theme CSS
22
+
23
+ Import the theme CSS file in your app's root layout or main CSS file:
24
+
25
+ ```css
26
+ /* In your global CSS file */
27
+ @import '@tydavidson/design-system/themes/theme.css';
28
+ ```
29
+
30
+ Or in your Next.js app:
31
+
32
+ ```tsx
33
+ // app/layout.tsx or pages/_app.tsx
34
+ import '@tydavidson/design-system/themes/theme.css';
35
+ ```
36
+
37
+ ### 2. Configure Tailwind CSS
38
+
39
+ Add the design system's color tokens to your `tailwind.config.js`:
40
+
41
+ ```js
42
+ // tailwind.config.js
43
+ module.exports = {
44
+ darkMode: ["class"],
45
+ content: [
46
+ "./src/**/*.{js,ts,jsx,tsx}",
47
+ "./node_modules/@tydavidson/design-system/dist/**/*.{js,mjs}",
48
+ ],
49
+ theme: {
50
+ extend: {
51
+ colors: {
52
+ // Background colors
53
+ bg: {
54
+ primary: 'var(--bg-primary)',
55
+ secondary: 'var(--bg-secondary)',
56
+ tertiary: 'var(--bg-tertiary)',
57
+ quaternary: 'var(--bg-quaternary)',
58
+ disabled: 'var(--bg-disabled)',
59
+ overlay: 'var(--bg-overlay)',
60
+ 'brand-primary': 'var(--bg-brand-primary)',
61
+ 'error-primary': 'var(--bg-error-primary)',
62
+ 'warning-primary': 'var(--bg-warning-primary)',
63
+ 'success-primary': 'var(--bg-success-primary)',
64
+ },
65
+ // Text colors
66
+ text: {
67
+ primary: 'var(--text-primary)',
68
+ secondary: 'var(--text-secondary)',
69
+ tertiary: 'var(--text-tertiary)',
70
+ disabled: 'var(--text-disabled)',
71
+ 'brand-primary': 'var(--text-brand-primary)',
72
+ 'error-primary': 'var(--text-error-primary)',
73
+ 'warning-primary': 'var(--text-warning-primary)',
74
+ 'success-primary': 'var(--text-success-primary)',
75
+ },
76
+ // Border colors
77
+ border: {
78
+ primary: 'var(--border-primary)',
79
+ secondary: 'var(--border-secondary)',
80
+ tertiary: 'var(--border-tertiary)',
81
+ disabled: 'var(--border-disabled)',
82
+ brand: 'var(--border-brand)',
83
+ error: 'var(--border-error)',
84
+ warning: 'var(--border-warning)',
85
+ success: 'var(--border-success)',
86
+ }
87
+ }
88
+ }
89
+ },
90
+ plugins: [],
91
+ }
92
+ ```
93
+
94
+ ## Theme Provider Setup
95
+
96
+ ### Next.js App Router
97
+
98
+ ```tsx
99
+ // app/layout.tsx
100
+ import { ThemeProvider } from '@tydavidson/design-system/themes';
101
+
102
+ export default function RootLayout({
103
+ children,
104
+ }: {
105
+ children: React.ReactNode;
106
+ }) {
107
+ return (
108
+ <html lang="en" suppressHydrationWarning>
109
+ <body>
110
+ <ThemeProvider>
111
+ {children}
112
+ </ThemeProvider>
113
+ </body>
114
+ </html>
115
+ );
116
+ }
117
+ ```
118
+
119
+ ### Next.js Pages Router
120
+
121
+ ```tsx
122
+ // pages/_app.tsx
123
+ import { ThemeProvider } from '@tydavidson/design-system/themes';
124
+
125
+ export default function App({ Component, pageProps }) {
126
+ return (
127
+ <ThemeProvider>
128
+ <Component {...pageProps} />
129
+ </ThemeProvider>
130
+ );
131
+ }
132
+ ```
133
+
134
+ ### React (Create React App)
135
+
136
+ ```tsx
137
+ // App.tsx
138
+ import { ThemeProvider } from '@tydavidson/design-system/themes';
139
+
140
+ function App() {
141
+ return (
142
+ <ThemeProvider>
143
+ {/* Your app content */}
144
+ </ThemeProvider>
145
+ );
146
+ }
147
+ ```
148
+
149
+ ## Usage Examples
150
+
151
+ ### Basic Theme Usage
152
+
153
+ ```tsx
154
+ import { useTheme, ThemeToggle } from '@tydavidson/design-system/themes';
155
+
156
+ function MyComponent() {
157
+ const { theme, setTheme, isDark } = useTheme();
158
+
159
+ return (
160
+ <div>
161
+ <p>Current theme: {theme}</p>
162
+ <p>Is dark mode: {isDark ? 'Yes' : 'No'}</p>
163
+ <ThemeToggle />
164
+ </div>
165
+ );
166
+ }
167
+ ```
168
+
169
+ ### Using UI Components
170
+
171
+ ```tsx
172
+ import { Button, Card, CardContent, CardHeader, CardTitle } from '@tydavidson/design-system';
173
+
174
+ function MyPage() {
175
+ return (
176
+ <Card>
177
+ <CardHeader>
178
+ <CardTitle>My Card</CardTitle>
179
+ </CardHeader>
180
+ <CardContent>
181
+ <Button>Click me</Button>
182
+ </CardContent>
183
+ </Card>
184
+ );
185
+ }
186
+ ```
187
+
188
+ ## Common Issues and Solutions
189
+
190
+ ### 1. Hydration Mismatch Errors
191
+
192
+ **Problem**: Server-side rendering doesn't match client-side rendering.
193
+
194
+ **Solution**:
195
+ - Add `suppressHydrationWarning` to your `<html>` element
196
+ - Use the `mounted` pattern for client-only components:
197
+
198
+ ```tsx
199
+ function ClientOnlyComponent() {
200
+ const [mounted, setMounted] = useState(false);
201
+
202
+ useEffect(() => {
203
+ setMounted(true);
204
+ }, []);
205
+
206
+ if (!mounted) return null;
207
+
208
+ return <ThemeToggle />;
209
+ }
210
+ ```
211
+
212
+ ### 2. CSS Variables Not Working
213
+
214
+ **Problem**: Theme colors aren't applying correctly.
215
+
216
+ **Solution**:
217
+ - Ensure you've imported the theme CSS file
218
+ - Check that your Tailwind config includes the color tokens
219
+ - Verify the CSS variables are being set on the `:root` element
220
+
221
+ ### 3. Icons Not Displaying
222
+
223
+ **Problem**: Icons appear as empty boxes or don't render.
224
+
225
+ **Solution**:
226
+ - Install required icon library: `npm install @tabler/icons-react`
227
+ - Ensure the icon library is available in your bundle
228
+
229
+ ### 4. TypeScript Errors
230
+
231
+ **Problem**: TypeScript can't find types for the design system.
232
+
233
+ **Solution**:
234
+ - The package includes TypeScript declarations
235
+ - Make sure your `tsconfig.json` includes `node_modules` in the module resolution
236
+ - If using path aliases, ensure they're configured correctly
237
+
238
+ ### 5. Bundle Size Issues
239
+
240
+ **Problem**: The design system is making your bundle too large.
241
+
242
+ **Solution**:
243
+ - The package uses tree-shaking, so unused components won't be included
244
+ - Icon libraries are external dependencies, so they won't be bundled
245
+ - Consider using dynamic imports for large components:
246
+
247
+ ```tsx
248
+ const DynamicComponent = dynamic(() => import('@tydavidson/design-system').then(mod => ({ default: mod.SomeLargeComponent })));
249
+ ```
250
+
251
+ ## Browser Compatibility
252
+
253
+ The design system supports:
254
+ - Modern browsers (Chrome, Firefox, Safari, Edge)
255
+ - React 18+
256
+ - Next.js 13+ (App Router and Pages Router)
257
+ - Create React App
258
+
259
+ ## Performance Considerations
260
+
261
+ 1. **Tree Shaking**: Only import what you need
262
+ 2. **CSS Variables**: Theme changes are handled via CSS variables for optimal performance
263
+ 3. **Icon Library**: Icons are external dependencies to avoid duplication
264
+ 4. **Bundle Splitting**: Consider code-splitting for large applications
265
+
266
+ ## Troubleshooting
267
+
268
+ If you encounter issues:
269
+
270
+ 1. Check the browser console for errors
271
+ 2. Verify all dependencies are installed
272
+ 3. Ensure CSS is properly imported
273
+ 4. Check that the ThemeProvider is wrapping your app
274
+ 5. Verify Tailwind configuration includes the design system's content paths
275
+
276
+ For additional help, refer to the [theme usage documentation](./theme-usage.md).