@formant/aesthetics 0.0.8 → 0.1.0

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 (10) hide show
  1. package/README.md +260 -84
  2. package/formant-aesthetics.css +1876 -0
  3. package/formant-layout-utilities.css +81 -0
  4. package/formant-properties.css +474 -0
  5. package/package.json +26 -75
  6. package/dist/components.css +0 -692
  7. package/dist/index.d.ts +0 -454
  8. package/dist/index.js +0 -5086
  9. package/dist/index.js.map +0 -1
  10. package/styles/globals.css +0 -180
package/README.md CHANGED
@@ -1,130 +1,306 @@
1
1
  # @formant/aesthetics
2
2
 
3
- Formant design system — themed React components built on shadcn/ui and Radix UI.
4
-
5
- [![npm version](https://badge.fury.io/js/@formant%2Faesthetics.svg)](https://www.npmjs.com/package/@formant/aesthetics)
3
+ A classless CSS framework based on the Formant Design System. No classes required—just semantic HTML that works out of the box. Perfect for rapid prototyping, documentation, and applications that want the Formant aesthetic without the complexity.
6
4
 
7
5
  ## Installation
8
6
 
7
+ ### NPM
8
+
9
9
  ```bash
10
10
  npm install @formant/aesthetics
11
11
  ```
12
12
 
13
- Peer dependencies required:
14
- ```bash
15
- npm install react react-dom
13
+ ### CDN (jsdelivr)
14
+
15
+ ```html
16
+ <!-- Complete framework (recommended) -->
17
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@formant/aesthetics@0.1.0/formant-aesthetics.css">
18
+
19
+ <!-- Design tokens only (build your own styles) -->
20
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@formant/aesthetics@0.1.0/formant-properties.css">
21
+
22
+ <!-- Layout utilities (optional) -->
23
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@formant/aesthetics@0.1.0/formant-layout-utilities.css">
16
24
  ```
17
25
 
18
26
  ## Quick Start
19
27
 
20
- ### 1. Wrap your app with FormantAesthetics
28
+ ### Option 1: Complete Classless CSS (Recommended)
29
+
30
+ Include the complete framework and write semantic HTML:
31
+
32
+ ```html
33
+ <!DOCTYPE html>
34
+ <html lang="en">
35
+ <head>
36
+ <meta charset="UTF-8">
37
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
38
+ <title>My App</title>
39
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@formant/aesthetics@0.1.0/formant-aesthetics.css">
40
+ </head>
41
+ <body>
42
+ <main>
43
+ <h1>Hello, Operator</h1>
44
+ <p>Your fleet is <strong>online</strong> and ready for <em>mission control</em>.</p>
45
+ <button>Deploy Fleet</button>
46
+ </main>
47
+ </body>
48
+ </html>
49
+ ```
21
50
 
22
- ```tsx
23
- import { FormantAesthetics } from "@formant/aesthetics";
51
+ ### Option 2: NPM + Module Import
24
52
 
25
- function App() {
26
- return (
27
- <FormantAesthetics>
28
- <YourApp />
29
- </FormantAesthetics>
30
- );
31
- }
53
+ ```javascript
54
+ // Import into your JS/TS project
55
+ import '@formant/aesthetics/formant-aesthetics.css';
32
56
  ```
33
57
 
34
- The `FormantAesthetics` component automatically injects all necessary CSS including:
35
- - Google Fonts (Inter, Space Grotesk, JetBrains Mono)
36
- - CSS variables for the Formant dark theme
37
- - All utility classes used by components
38
-
39
- ### 2. Use Components
40
-
41
- ```tsx
42
- import { Button, Card, CardHeader, CardTitle, Badge } from "@formant/aesthetics";
43
-
44
- function MyComponent() {
45
- return (
46
- <div className="min-h-screen bg-background text-foreground p-8">
47
- <Card>
48
- <CardHeader>
49
- <CardTitle>Hello @formant/aesthetics</CardTitle>
50
- <Badge>v0.0.3</Badge>
51
- </CardHeader>
52
- <div className="p-6 space-y-4">
53
- <Button>Default</Button>
54
- <Button variant="secondary">Secondary</Button>
55
- <Button variant="destructive">Destructive</Button>
56
- </div>
57
- </Card>
58
- </div>
59
- );
60
- }
58
+ Or in your CSS/SCSS:
59
+
60
+ ```css
61
+ @import '@formant/aesthetics/formant-aesthetics.css';
61
62
  ```
62
63
 
63
- That's it! No build step or CSS configuration required. The `FormantAesthetics` component handles everything.
64
+ ### Option 3: CSS Properties Only
64
65
 
65
- ## Optional: Import Global Styles
66
+ Use just the design tokens to build custom styles:
66
67
 
67
- If you prefer to include styles in your own CSS pipeline, you can import the base theme:
68
+ ```html
69
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@formant/aesthetics@0.1.0/formant-properties.css">
70
+ ```
68
71
 
69
72
  ```css
70
- @import "@formant/aesthetics/styles";
73
+ .my-component {
74
+ background-color: var(--theme-neutrals-0);
75
+ color: var(--theme-atmospheric-accents-2);
76
+ font-family: var(--font-display);
77
+ border: 1px solid var(--theme-atmospheric-accents-1);
78
+ }
71
79
  ```
72
80
 
73
- Then use the `ThemeProvider` directly instead of `FormantAesthetics`:
81
+ ### Option 4: Add Layout Utilities
74
82
 
75
- ```tsx
76
- import { ThemeProvider } from "@formant/aesthetics";
83
+ For grid and flexbox utilities alongside the classless CSS:
77
84
 
78
- function App() {
79
- return (
80
- <ThemeProvider>
81
- <YourApp />
82
- </ThemeProvider>
83
- );
84
- }
85
+ ```html
86
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@formant/aesthetics@0.1.0/formant-aesthetics.css">
87
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@formant/aesthetics@0.1.0/formant-layout-utilities.css">
85
88
  ```
86
89
 
87
90
  ## What's Included
88
91
 
89
- - **40+ shadcn/ui components** — Accordion, Alert, Badge, Button, Card, Dialog, Dropdown, Form, Input, Select, Table, Tabs, Toast, etc.
90
- - **Formant brand components** — `FormantLogo`, `FormantLogoWithText`, `AIChat`, `KnowledgeGraph`
91
- - **Theme provider** — `ThemeProvider` from next-themes (dark/light mode)
92
- - **Charts** — Recharts components (BarChart, LineChart, PieChart, etc.)
93
- - **Utilities** — `cn()` for class merging
92
+ | File | Size | Description |
93
+ |------|------|-------------|
94
+ | `formant-aesthetics.css` | ~8KB | Complete classless CSS framework |
95
+ | `formant-properties.css` | ~2KB | Design tokens only (CSS variables) |
96
+ | `formant-layout-utilities.css` | ~3KB | Grid/flex layout utilities |
94
97
 
95
- ## Development
98
+ ## Design Tokens (Theme-Based Naming)
96
99
 
97
- ```bash
98
- # Install dependencies
99
- npm install
100
+ ### Theme Colors
101
+
102
+ #### Neutrals (0-3)
103
+
104
+ | Token | Hex | Name | Usage |
105
+ |-------|-----|------|-------|
106
+ | `--theme-neutrals-0` | `#0A0F11` | Deep Command | Primary backgrounds, the void |
107
+ | `--theme-neutrals-1` | `#202428` | Slate Mist | Card backgrounds, secondary surfaces |
108
+ | `--theme-neutrals-2` | `#A3ABA9` | System Neutral | Body text, captions, border base |
109
+ | `--theme-neutrals-3` | `#F2F3F4` | Formant White | Primary text, headlines |
110
+
111
+ #### Atmospheric Accents (0-2)
112
+
113
+ | Token | Hex | Name | Usage |
114
+ |-------|-----|------|-------|
115
+ | `--theme-atmospheric-accents-0` | `#2C4142` | Ethereal Teal | Active states, hover backgrounds |
116
+ | `--theme-atmospheric-accents-1` | `#4B5E53` | Fog Green | Borders, dividers, structure |
117
+ | `--theme-atmospheric-accents-2` | `#ACC3B3` | Horizon Glow | CTAs, interactive elements, links |
118
+
119
+ #### Functional Accents (0-1)
120
+
121
+ | Token | Hex | Name | Usage |
122
+ |-------|-----|------|-------|
123
+ | `--theme-functional-accents-0` | `#E8AB7F` | Terminal Amber | Warnings, attention, alarms |
124
+ | `--theme-functional-accents-1` | `#8B8CF4` | Interface Iris | AI states, system intelligence |
125
+
126
+ ### Typography
127
+
128
+ | Token | Font | Usage |
129
+ |-------|------|-------|
130
+ | `--font-display` | Space Grotesk | Headlines, H1-H6, architectural voice |
131
+ | `--font-body` | Inter | Body text, paragraphs, UI elements |
132
+ | `--font-monospace` | JetBrains Mono | Code, data, labels, system status |
100
133
 
101
- # Build the library
102
- npm run build
134
+ ### Semantic Mappings
103
135
 
104
- # Watch mode for development
105
- npm run dev
136
+ | Token | Maps To | Usage |
137
+ |-------|---------|-------|
138
+ | `--formant-bg-primary` | `--theme-neutrals-0` | Page backgrounds |
139
+ | `--formant-bg-secondary` | `--theme-neutrals-1` | Cards, elevated surfaces |
140
+ | `--formant-text-primary` | `--theme-neutrals-3` | Headlines, primary text |
141
+ | `--formant-text-secondary` | `--theme-neutrals-2` | Body text, captions |
142
+ | `--formant-accent-primary` | `--theme-atmospheric-accents-2` | Buttons, links, interactive |
143
+ | `--formant-accent-secondary` | `--theme-atmospheric-accents-0` | Active states, hover |
144
+ | `--formant-accent-warning` | `--theme-functional-accents-0` | Warnings, errors |
145
+ | `--formant-accent-ai` | `--theme-functional-accents-1` | AI indicators |
106
146
 
107
- # Type check
108
- npm run typecheck
147
+ ## HTML Element Showcase
148
+
149
+ ### Typography
150
+
151
+ ```html
152
+ <h1>Heading Level 1</h1>
153
+ <h2>Heading Level 2</h2>
154
+ <h3>Heading Level 3 (Accent Color)</h3>
155
+
156
+ <p>Body text with <strong>bold</strong>, <em>italic</em>, and <code>inline code</code>.</p>
157
+
158
+ <blockquote>
159
+ <p>A quoted statement with architectural authority.</p>
160
+ <cite>— Source Attribution</cite>
161
+ </blockquote>
162
+
163
+ <pre><code>// Code blocks use --font-monospace
164
+ const fleet = await deploy({ autonomous: true });</code></pre>
165
+ ```
166
+
167
+ ### Forms
168
+
169
+ ```html
170
+ <form>
171
+ <label for="email">Email Address</label>
172
+ <input type="email" id="email" placeholder="ops@formant.io" required>
173
+
174
+ <label for="message">Message</label>
175
+ <textarea id="message"></textarea>
176
+
177
+ <label>
178
+ <input type="checkbox"> Enable Autonomy
179
+ </label>
180
+
181
+ <label>
182
+ <input type="radio" name="priority" value="high"> High Priority
183
+ </label>
184
+
185
+ <button type="submit">Submit</button>
186
+ <button type="button">Cancel</button>
187
+ </form>
188
+ ```
189
+
190
+ ### Data Attributes
191
+
192
+ ```html
193
+ <!-- Eyebrow Label -->
194
+ <div data-eyebrow>Section Label</div>
195
+
196
+ <!-- Status Tags -->
197
+ <span data-tag="resolved">RESOLVED</span>
198
+ <span data-tag="investigating">INVESTIGATING</span>
199
+ <span data-tag="warning">WARNING</span>
200
+ <span data-tag="ai-active">AI ACTIVE</span>
201
+
202
+ <!-- Alert Boxes -->
203
+ <div data-alert="info">Information message</div>
204
+ <div data-alert="warning">Warning message</div>
205
+ <div data-alert="ai">AI system message</div>
109
206
  ```
110
207
 
111
- ## Architecture
208
+ ## Button Types
209
+
210
+ ```html
211
+ <button>Primary Action</button>
212
+ <button type="button">Secondary Action</button>
213
+ <button type="reset">Tertiary/Reset</button>
214
+ <button data-variant="warning">Warning Action</button>
215
+ ```
216
+
217
+ ## Layout Utilities
218
+
219
+ When using `formant-layout-utilities.css`:
220
+
221
+ ```html
222
+ <!-- Grid layouts -->
223
+ <div data-grid="2">
224
+ <div>Column 1</div>
225
+ <div>Column 2</div>
226
+ </div>
227
+
228
+ <!-- Flex layouts -->
229
+ <div data-flex="row" data-gap="2">
230
+ <div>Item 1</div>
231
+ <div>Item 2</div>
232
+ </div>
233
+
234
+ <!-- Container -->
235
+ <div data-container>
236
+ <p>Centered content with max-width</p>
237
+ </div>
238
+ ```
239
+
240
+ ## Full Example Page
241
+
242
+ ```html
243
+ <!DOCTYPE html>
244
+ <html lang="en">
245
+ <head>
246
+ <meta charset="UTF-8">
247
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
248
+ <title>Fleet Dashboard</title>
249
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@formant/aesthetics@0.1.0/formant-aesthetics.css">
250
+ <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@formant/aesthetics@0.1.0/formant-layout-utilities.css">
251
+ </head>
252
+ <body>
253
+ <header data-container>
254
+ <div data-eyebrow>MISSION CONTROL</div>
255
+ <h1>Fleet Status Overview</h1>
256
+ </header>
257
+
258
+ <main data-container>
259
+ <div data-grid="3">
260
+ <article>
261
+ <h3>Online Robots</h3>
262
+ <p data-tag="resolved">12 ACTIVE</p>
263
+ </article>
264
+ <article>
265
+ <h3>Alerts</h3>
266
+ <p data-tag="warning">2 PENDING</p>
267
+ </article>
268
+ <article>
269
+ <h3>AI Systems</h3>
270
+ <p data-tag="ai-active">OPERATIONAL</p>
271
+ </article>
272
+ </div>
273
+
274
+ <div data-alert="info">
275
+ All systems nominal. Fleet ready for autonomous operations.
276
+ </div>
277
+
278
+ <h2>Recent Commands</h2>
279
+ <table>
280
+ <thead>
281
+ <tr><th>Time</th><th>Robot</th><th>Command</th><th>Status</th></tr>
282
+ </thead>
283
+ <tbody>
284
+ <tr><td>10:42 AM</td><td>Spot-01</td><td>Go to waypoint</td><td data-tag="resolved">Complete</td></tr>
285
+ <tr><td>10:38 AM</td><td>Drone-03</td><td>Survey perimeter</td><td data-tag="investigating">In Progress</td></tr>
286
+ </tbody>
287
+ </table>
288
+ </main>
289
+ </body>
290
+ </html>
291
+ ```
112
292
 
113
- - **Source**: TypeScript React components in `components/`
114
- - **Build**: `tsup` compiles to `dist/index.js` + `dist/index.d.ts`
115
- - **Styling**: Static CSS injected by `FormantAesthetics` component — no external CSS build step required
116
- - **Distribution**: Published to npm as `@formant/aesthetics`
293
+ ## Browser Support
117
294
 
118
- ## Migration from Tailwind
295
+ - Chrome/Edge 88+
296
+ - Firefox 78+
297
+ - Safari 14+
119
298
 
120
- If you were previously using the Tailwind version of @formant/aesthetics:
299
+ Requires CSS Custom Properties support.
121
300
 
122
- 1. Remove Tailwind CSS from your project
123
- 2. Remove `@tailwindcss/postcss` from your PostCSS config
124
- 3. Remove the safelist copy script from your `postinstall`
125
- 4. Wrap your app with `FormantAesthetics` instead of importing CSS files
301
+ ## Version
126
302
 
127
- All component props and APIs remain exactly the same.
303
+ 0.1.0 — Aligned with Formant Design System Version 2026.1
128
304
 
129
305
  ## License
130
306