@conscia-labs/design-system 1.0.3 → 1.2.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.
- package/AGENT_GUIDE.md +222 -0
- package/README.md +113 -837
- package/agent-manifest.json +472 -0
- package/bin/conscia-design-system.mjs +109 -0
- package/dist/{chunk-HAJMOT3P.js → chunk-HWUUODVE.js} +2 -2
- package/dist/chunk-HWUUODVE.js.map +1 -0
- package/dist/{chunk-LPUWW7XF.js → chunk-OYJH5CVD.js} +545 -252
- package/dist/chunk-OYJH5CVD.js.map +1 -0
- package/dist/{chunk-QP3SEL2Z.js → chunk-SIRISAFC.js} +2 -2
- package/dist/foundation.css +76 -19
- package/dist/index.d.ts +1 -1
- package/dist/index.js +27 -3
- package/dist/patterns/index.d.ts +86 -7
- package/dist/patterns/index.js +26 -2
- package/dist/primitives/index.d.ts +2 -2
- package/dist/primitives/index.js +2 -2
- package/dist/standalone.css +1 -1
- package/dist/styles.css +76 -19
- package/package.json +19 -6
- package/dist/chunk-HAJMOT3P.js.map +0 -1
- package/dist/chunk-LPUWW7XF.js.map +0 -1
- /package/dist/{chunk-QP3SEL2Z.js.map → chunk-SIRISAFC.js.map} +0 -0
package/AGENT_GUIDE.md
ADDED
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
# Conscia Design System: Agent Guide
|
|
2
|
+
|
|
3
|
+
This file is the compact, version-matched contract for coding agents working in
|
|
4
|
+
an application that has `@conscia-labs/design-system` installed. Read the
|
|
5
|
+
installed copy before changing application UI. The installed package version is
|
|
6
|
+
authoritative when this guide differs from documentation on `main`.
|
|
7
|
+
|
|
8
|
+
## Start here
|
|
9
|
+
|
|
10
|
+
1. Inspect the application's existing shell, global stylesheet, routing, and
|
|
11
|
+
nearby design-system usage before editing.
|
|
12
|
+
2. Reuse a public Conscia pattern when one matches the workflow. Use primitives
|
|
13
|
+
when the application genuinely needs a composition the package does not own.
|
|
14
|
+
3. Import only public exports. Do not reach into `dist` or package internals.
|
|
15
|
+
4. Preserve the application's routing, authentication, permissions, data,
|
|
16
|
+
mutations, validation, and business behavior.
|
|
17
|
+
5. Verify the affected UI at desktop and mobile sizes, including keyboard and
|
|
18
|
+
visible focus behavior for interactive changes.
|
|
19
|
+
|
|
20
|
+
Live examples and component guidance:
|
|
21
|
+
<https://conscia-labs.github.io/design-system/>
|
|
22
|
+
|
|
23
|
+
Machine-readable component inventory:
|
|
24
|
+
<https://conscia-labs.github.io/design-system/agent-manifest.json>
|
|
25
|
+
|
|
26
|
+
## Installation contract
|
|
27
|
+
|
|
28
|
+
Tailwind CSS v4 applications import these styles once from their global CSS:
|
|
29
|
+
|
|
30
|
+
```css
|
|
31
|
+
@import "tailwindcss";
|
|
32
|
+
@import "@conscia-labs/design-system/tailwind.css";
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Do not add another `@source` for the package. The published stylesheet already
|
|
36
|
+
contains the package-relative source declaration.
|
|
37
|
+
|
|
38
|
+
Applications that do not run Tailwind use the complete precompiled bundle:
|
|
39
|
+
|
|
40
|
+
```css
|
|
41
|
+
@import "@conscia-labs/design-system/standalone.css";
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Never import `standalone.css` in a Tailwind application. Its preflight and
|
|
45
|
+
utilities would compete with the application's generated CSS.
|
|
46
|
+
|
|
47
|
+
Set shared preferences on the document root:
|
|
48
|
+
|
|
49
|
+
```tsx
|
|
50
|
+
<html
|
|
51
|
+
lang="en"
|
|
52
|
+
data-appearance="system"
|
|
53
|
+
data-density="comfortable"
|
|
54
|
+
suppressHydrationWarning
|
|
55
|
+
>
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Supported appearance values are `light`, `dark`, and `system`. Supported
|
|
59
|
+
density values are `comfortable`, `compact`, and `operational`.
|
|
60
|
+
|
|
61
|
+
## Non-negotiable boundaries
|
|
62
|
+
|
|
63
|
+
- Do not copy design-system components into the application.
|
|
64
|
+
- Do not install `@base-ui/react`, `@radix-ui/*`, or copied shadcn components
|
|
65
|
+
when the design system already provides the behavior.
|
|
66
|
+
- Do not use the removed `asChild` API. Use the documented `render` prop for
|
|
67
|
+
custom-host composition.
|
|
68
|
+
- Do not use legacy utilities such as `bg-primary`, `bg-muted`, `border-input`,
|
|
69
|
+
or their associated legacy variables. Use Conscia semantic roles.
|
|
70
|
+
- Do not reach into package implementation files or depend on Base UI details.
|
|
71
|
+
- Do not add application z-index workarounds for supported overlays before
|
|
72
|
+
checking the documented `modal` behavior.
|
|
73
|
+
- Do not encode status using color alone. Retain meaningful text, labels, or
|
|
74
|
+
icons.
|
|
75
|
+
|
|
76
|
+
## Choose the highest useful level
|
|
77
|
+
|
|
78
|
+
### Patterns
|
|
79
|
+
|
|
80
|
+
Prefer patterns for recurring product workflows:
|
|
81
|
+
|
|
82
|
+
- Application chrome: `AppShell`, `AppHeader`, `AppSidebar`, `MainRegion`,
|
|
83
|
+
`PageFrame`, and `SidebarNavigation`.
|
|
84
|
+
- Page composition: `PageHeader`, `PageToolbar`, `ResourceSummary`, and
|
|
85
|
+
`DetailSection`.
|
|
86
|
+
- Data-heavy collections: `DataTable`, `EntityTable`, `InventorySurface`, and
|
|
87
|
+
`PaginationControls`.
|
|
88
|
+
- Operational dashboards: `MetricCard`, `MetricBand`, `DataPanel`,
|
|
89
|
+
`AttentionList`, and `ActivityList`.
|
|
90
|
+
- States and feedback: `StateView`, `ErrorState`, `LoadingRows`,
|
|
91
|
+
`ConfirmationDialog`, `CommandPalette`, and `FilterBar`.
|
|
92
|
+
- Multi-rail workspaces: the `Workbench*` family.
|
|
93
|
+
|
|
94
|
+
### Primitives
|
|
95
|
+
|
|
96
|
+
Use primitives for application-specific compositions: `Button`, `Card`,
|
|
97
|
+
`Field`, `Input`, `Select`, `SearchableSelect`, `Dialog`, `Sheet`, `Popover`,
|
|
98
|
+
`Tabs`, `Table`, `Badge`, `Alert`, `Toast`, and related anatomy exports.
|
|
99
|
+
|
|
100
|
+
Consult `agent-manifest.json` for the complete public runtime inventory and the
|
|
101
|
+
playground route for each family.
|
|
102
|
+
|
|
103
|
+
## Frequent decisions
|
|
104
|
+
|
|
105
|
+
- Use `Table` for semantic table anatomy. Use `DataTable` for sorting,
|
|
106
|
+
selection, column definitions, responsive rows, or pagination.
|
|
107
|
+
- Use `Tabs` for layered content or mode switching. Use `NavigationTabs` for
|
|
108
|
+
route-backed destinations.
|
|
109
|
+
- Use `Select` for a short, familiar list. Use `SearchableSelect` for longer
|
|
110
|
+
lists that users need to filter.
|
|
111
|
+
- Use `LoadingButton` for asynchronous actions so layout, disabled state, and
|
|
112
|
+
`aria-busy` remain consistent.
|
|
113
|
+
- Use `ConfirmationDialog` or `AlertDialog` only for consequential decisions.
|
|
114
|
+
- Use `operational` density for information-heavy administration, inventory,
|
|
115
|
+
and workspace surfaces. Keep `comfortable` for general-purpose product UI.
|
|
116
|
+
|
|
117
|
+
## Composition examples
|
|
118
|
+
|
|
119
|
+
Use fields as the unit of form layout and accessible help/error content:
|
|
120
|
+
|
|
121
|
+
```tsx
|
|
122
|
+
import {
|
|
123
|
+
Button,
|
|
124
|
+
Field,
|
|
125
|
+
FieldDescription,
|
|
126
|
+
FieldLabel,
|
|
127
|
+
Input,
|
|
128
|
+
} from "@conscia-labs/design-system";
|
|
129
|
+
|
|
130
|
+
<form className="grid gap-5">
|
|
131
|
+
<Field>
|
|
132
|
+
<FieldLabel htmlFor="connection-name">Name</FieldLabel>
|
|
133
|
+
<Input id="connection-name" name="name" />
|
|
134
|
+
<FieldDescription>Use a name operators will recognize.</FieldDescription>
|
|
135
|
+
</Field>
|
|
136
|
+
<Button type="submit">Create connection</Button>
|
|
137
|
+
</form>;
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Keep popup controls non-modal when nested inside a modal surface:
|
|
141
|
+
|
|
142
|
+
```tsx
|
|
143
|
+
<Dialog open={open} onOpenChange={setOpen}>
|
|
144
|
+
<DialogContent>
|
|
145
|
+
<DialogBody>
|
|
146
|
+
<FormSelect modal={false} name="vendor" options={vendorOptions} />
|
|
147
|
+
<SearchableSelect
|
|
148
|
+
modal={false}
|
|
149
|
+
name="model"
|
|
150
|
+
options={modelOptions}
|
|
151
|
+
onValueChange={setModel}
|
|
152
|
+
/>
|
|
153
|
+
</DialogBody>
|
|
154
|
+
</DialogContent>
|
|
155
|
+
</Dialog>
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Prefer the integrated global header for new application shells:
|
|
159
|
+
|
|
160
|
+
```tsx
|
|
161
|
+
<AppShell headerLayout="integrated">
|
|
162
|
+
<AppHeader>
|
|
163
|
+
<AppHeaderStart>
|
|
164
|
+
<SidebarTrigger />
|
|
165
|
+
{productIdentity}
|
|
166
|
+
</AppHeaderStart>
|
|
167
|
+
<AppHeaderSearch>{globalSearch}</AppHeaderSearch>
|
|
168
|
+
<AppHeaderActions>{accountActions}</AppHeaderActions>
|
|
169
|
+
</AppHeader>
|
|
170
|
+
<AppSidebar variant="auto">
|
|
171
|
+
<AppSidebarContent>{navigation}</AppSidebarContent>
|
|
172
|
+
</AppSidebar>
|
|
173
|
+
<MainRegion>{children}</MainRegion>
|
|
174
|
+
</AppShell>
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
## Styling
|
|
178
|
+
|
|
179
|
+
Use semantic tokens and utilities rather than palette colors:
|
|
180
|
+
|
|
181
|
+
- Surfaces: `canvas`, `surface`, `surface-raised`, `surface-muted`, and
|
|
182
|
+
`surface-floating`.
|
|
183
|
+
- Text: `text-primary`, `text-secondary`, `text-supporting`, and `text-muted`.
|
|
184
|
+
- Brand: `brand` with `brand-foreground` for burgundy identity surfaces,
|
|
185
|
+
`brand-accent` for blue emphasis, and `brand-supporting-*` for restrained
|
|
186
|
+
green expression. Use the matching foreground token on filled surfaces.
|
|
187
|
+
- Actions and selection: `action-*` and `selection-*`.
|
|
188
|
+
- Status: `information-*`, `success-*`, `warning-*`, and `danger-*`.
|
|
189
|
+
- Neutral structure: `border-subtle`, `control-border`, and shared radius,
|
|
190
|
+
spacing, type, elevation, and focus tokens.
|
|
191
|
+
|
|
192
|
+
Use `className` for layout and local composition. Override semantic variables
|
|
193
|
+
only when the product intentionally changes a system-level decision. Avoid
|
|
194
|
+
component descendant selectors.
|
|
195
|
+
|
|
196
|
+
The low-level `palette-burgundy`, `palette-electric-blue`, and `palette-green`
|
|
197
|
+
variables preserve official brand values, but applications should compose with
|
|
198
|
+
the semantic brand roles above. Do not use `text-brand` as ordinary text on a
|
|
199
|
+
dark canvas; burgundy is intentionally stable across appearances and is
|
|
200
|
+
designed as an identity surface with `text-brand-foreground`.
|
|
201
|
+
|
|
202
|
+
## Accessibility ownership
|
|
203
|
+
|
|
204
|
+
The package provides component-level keyboard behavior, focus management, and
|
|
205
|
+
semantic structure. The application remains responsible for:
|
|
206
|
+
|
|
207
|
+
- Meaningful labels and accessible names.
|
|
208
|
+
- Heading order and page landmarks.
|
|
209
|
+
- Form validation messages and their relationships.
|
|
210
|
+
- Alternative text.
|
|
211
|
+
- Route state such as `aria-current`.
|
|
212
|
+
- Complete keyboard-accessible business workflows.
|
|
213
|
+
|
|
214
|
+
## Verification
|
|
215
|
+
|
|
216
|
+
Use the consuming application's own commands. At minimum, run its typecheck and
|
|
217
|
+
tests for behavior changes, then inspect the affected route in light and dark
|
|
218
|
+
appearance at desktop and mobile sizes. For interactive changes, exercise the
|
|
219
|
+
keyboard path, focus return, disabled or pending state, and any nested overlay.
|
|
220
|
+
|
|
221
|
+
For migration work, use the versioned migration guide linked from the package
|
|
222
|
+
README. Do not infer compatibility from old shadcn or Radix usage.
|