@lukeashford/aurelius 2.11.0 → 2.13.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 +109 -118
  2. package/dist/index.d.mts +266 -24
  3. package/dist/index.d.ts +266 -24
  4. package/dist/index.js +1042 -338
  5. package/dist/index.js.map +1 -1
  6. package/dist/index.mjs +984 -294
  7. package/dist/index.mjs.map +1 -1
  8. package/dist/styles/theme.css +20 -0
  9. package/llms.md +294 -82
  10. package/package.json +1 -1
package/README.md CHANGED
@@ -1,161 +1,152 @@
1
- # Aurelius
1
+ # Aurelius — Agent Development Guide
2
2
 
3
- [![npm version](https://img.shields.io/npm/v/@lukeashford/aurelius.svg)](https://www.npmjs.com/package/@lukeashford/aurelius)
4
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
3
+ This file provides instructions for AI coding agents working **on** this repository (developing the
4
+ library itself).
5
5
 
6
- **A dark-mode design system for creative technologists** — combining technical sophistication with a
7
- cinematic aesthetic.
8
-
9
- [Live Demo](https://aurelius.lukeashford.com/)
6
+ For agents **using** the library in other projects, see `llms.md`.
10
7
 
11
8
  ---
12
9
 
13
- ## Philosophy
14
-
15
- Aurelius relies on deep blacks, rich golds, and refined typography to convey stability, trust, and
16
- quiet luxury.
17
-
18
- **Core principles:**
19
-
20
- - **Cinematic:** Strictly dark mode. No white backgrounds.
21
- - **Refined:** Gold (`#c9a227`) is reserved for primary actions and key highlights.
22
- - **Grounded:** Subtle 1px borders over heavy drop shadows.
10
+ ## README
23
11
 
24
- **Usage hierarchy:**
25
-
26
- 1. **React Components** — Use `<Button />`, `<Card />`, etc. whenever possible
27
- 2. **Tailwind utilities** — Build custom layouts with token-based classes (`bg-obsidian`,
28
- `text-gold`)
29
- 3. **Design tokens** — Direct access to values as a last resort
12
+ See @README.md for project orientation, philosophy, and quick start commands.
30
13
 
31
14
  ---
32
15
 
33
- ## AI Agent Optimization 🤖
34
-
35
- This package includes a machine-readable manifest and ESLint enforcement for AI coding assistants.
36
-
37
- **Prompt your agent:**
16
+ ## Project Structure
38
17
 
39
- > Use the Aurelius design system for this project.
40
- >
41
- > 1. Run `npm install @lukeashford/aurelius`
42
- > 2. Read `node_modules/@lukeashford/aurelius/llms.md` completely before writing any code
43
- > 3. Follow its setup instructions (Tailwind config, ESLint, fonts)
44
- > 4. Use only the components and Tailwind classes listed in that file
18
+ ```
19
+ aurelius/
20
+ ├── src/ # Library source code
21
+ │ ├── components/ # React components
22
+ │ │ ├── chat/ # Chat interface components
23
+ │ │ │ └── hooks/ # React hooks (useArtifacts, useScrollAnchor, etc.)
24
+ │ │ └── icons/ # Icon components
25
+ │ ├── styles/ # CSS and theme definitions
26
+ │ │ ├── base.css # Entry point (imports theme + Tailwind)
27
+ │ │ └── theme.css # Design tokens and custom utilities
28
+ │ └── utils/ # Utility functions (cx, etc.)
29
+ ├── demo/ # Demo site (Vite + React)
30
+ │ └── src/components/ # Demo components (ChatDemo, etc.)
31
+ ├── scripts/ # Build scripts
32
+ │ └── generate-manifest.js # Generates llms.md from source
33
+ ├── llms.md # Auto-generated AI manifest (DO NOT EDIT)
34
+ ├── CLAUDE.md # This file
35
+ └── README.md # Human-readable overview
36
+ ```
45
37
 
46
- The manifest provides complete setup instructions, so agents can bootstrap a project from scratch
47
- while staying within design system constraints.
38
+ ---
48
39
 
49
- [View the manifest](./llms.md)
40
+ ## Development Guidelines
50
41
 
51
- ---
42
+ ### Adding Components
52
43
 
53
- ## Quick Start
44
+ 1. Create component file in `src/components/` (or appropriate subdirectory)
45
+ 2. Add JSDoc comments to the component and its props interface — these are auto-extracted to
46
+ `llms.md`
47
+ 3. Export from `src/components/index.ts`
48
+ 4. Run `npm run build` to regenerate `llms.md`
54
49
 
55
- ### 1. Install
50
+ ### JSDoc Format for Props
56
51
 
57
- ```bash
58
- # For Vite projects (Recommended)
59
- npm install @lukeashford/aurelius
60
- npm install -D tailwindcss @tailwindcss/vite eslint @typescript-eslint/parser eslint-plugin-better-tailwindcss @poupe/eslint-plugin-tailwindcss @eslint/css tailwind-csstree
52
+ ```tsx
53
+ export interface MyComponentProps {
54
+ /**
55
+ * Description of this prop
56
+ */
57
+ propName: string
58
+ /**
59
+ * Another prop with type annotation in description
60
+ * @default "defaultValue"
61
+ */
62
+ optionalProp?: 'option1' | 'option2'
63
+ }
61
64
 
62
- # For other projects
63
- # npm install -D tailwindcss @tailwindcss/postcss postcss ...
65
+ /**
66
+ * Component description goes here.
67
+ * This will be extracted to llms.md.
68
+ */
69
+ export function MyComponent({propName, optionalProp = 'option1'}: MyComponentProps) {
70
+ // ...
71
+ }
64
72
  ```
65
73
 
66
- ### 2. Configure (Vite)
74
+ ### Tailwind CSS v4
67
75
 
68
- If you are using Vite, add the Tailwind CSS plugin to your `vite.config.ts`:
76
+ This project uses Tailwind CSS v4 with `@theme` design tokens:
69
77
 
70
- ```typescript
71
- import {defineConfig} from 'vite'
72
- import tailwindcss from '@tailwindcss/vite'
78
+ - All colors defined in `src/styles/theme.css` under `@theme { }`
79
+ - Custom utilities defined with `@utility` directive
80
+ - ESLint enforces design system constraints (no arbitrary values)
73
81
 
74
- export default defineConfig({
75
- plugins: [
76
- tailwindcss(),
77
- ],
78
- })
79
- ```
82
+ **Restricted patterns (will fail lint):**
80
83
 
81
- ### 3. Import the design system
84
+ - `bg-[#...]`, `text-[...]` — arbitrary color values
85
+ - `rounded-sm`, `rounded` — use design system border radius
86
+ - `max-h-[...]`, `w-[...]` — use relative units or design tokens
82
87
 
83
- Create or update your `index.css`:
88
+ ### Testing Changes
84
89
 
85
- ```css
86
- /* Import the complete Aurelius design system (includes Tailwind v4, fonts, and theme) */
87
- @import '@lukeashford/aurelius/styles/base.css';
90
+ ```bash
91
+ # Type check
92
+ npm run typecheck
88
93
 
89
- /* Tell Tailwind to scan the Aurelius package for utility classes */
90
- @source "../node_modules/@lukeashford/aurelius/dist";
91
- ```
94
+ # Lint (must pass with 0 warnings)
95
+ npm run lint
92
96
 
93
- Then import it in your entry file:
97
+ # Full build (typecheck + lint + compile + generate manifest)
98
+ npm run build
94
99
 
95
- ```typescript
96
- // main.tsx or index.tsx
97
- import './index.css'
100
+ # Run demo to visually test
101
+ npm run dev:demo
98
102
  ```
99
103
 
100
- ### 4. Configure ESLint (simplest form)
104
+ ### Documentation
101
105
 
102
- Aurelius ships with a default ESLint config you can re-export in one line. It enforces design system
103
- constraints — if ESLint complains, you're leaving the rails.
106
+ - **README.md** — Keep focused on human orientation. No component API docs.
107
+ - **llms.md** — Auto-generated. Never edit directly. Add JSDoc to components instead.
108
+ - **CLAUDE.md** — This file. Update when project structure or processes change.
104
109
 
105
- ```javascript
106
- // eslint.config.mjs
107
- export {default} from '@lukeashford/aurelius/eslint';
108
- ```
110
+ ### Commit Guidelines
109
111
 
110
- **Need a different CSS entry point?**
112
+ - Use conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`
113
+ - Run `npm run build` before committing to ensure everything compiles
114
+ - The build regenerates `llms.md` — commit it with your changes
111
115
 
112
- ```javascript
113
- // eslint.config.mjs
114
- import {createAureliusESLintConfig} from '@lukeashford/aurelius/eslint';
116
+ ---
115
117
 
116
- export default createAureliusESLintConfig({
117
- entryPoint: './app/styles.css'
118
- });
119
- ```
118
+ ## Key Files
120
119
 
121
- **What this enforces:**
120
+ | File | Purpose |
121
+ |---------------------------------------------|------------------------------------------|
122
+ | `src/styles/theme.css` | Design tokens (colors, fonts, utilities) |
123
+ | `src/components/index.ts` | Main export barrel |
124
+ | `src/components/chat/hooks/useArtifacts.ts` | Artifacts panel state management |
125
+ | `src/components/chat/ChatInterface.tsx` | Main chat orchestrator component |
126
+ | `scripts/generate-manifest.js` | Generates llms.md from source |
127
+ | `eslint/index.js` | ESLint config enforcing design system |
122
128
 
123
- - **JS/TS/JSX/TSX files:** No custom/non-Aurelius class names, no arbitrary value utilities like
124
- `bg-[#123456]` or `text-[15px]`
125
- - **CSS files:** Tailwind v4 CSS best practices, valid `@apply` directives, no arbitrary value
126
- overuse, and proper theme token usage
129
+ ---
127
130
 
128
- ### 5. Update package.json scripts
131
+ ## Common Tasks
129
132
 
130
- Add a lint script and wire it into your workflow:
133
+ ### Add a new icon
131
134
 
132
- ```json
133
- {
134
- "scripts": {
135
- "lint": "eslint src --max-warnings 0",
136
- "dev": "npm run lint && vite",
137
- "build": "npm run lint && vite build"
138
- }
139
- }
140
- ```
135
+ 1. Create `src/components/icons/MyIcon.tsx`
136
+ 2. Add React import and IconProps type
137
+ 3. Export from `src/components/icons/index.ts`
138
+ 4. Export from `src/components/index.ts`
141
139
 
142
- If your project already has CI (or you're asked to add one), include `npm run lint` in that
143
- pipeline so lint failures block merges.
140
+ ### Add a new color token
144
141
 
145
- ### 6. Use components
142
+ 1. Add to `@theme { }` block in `src/styles/theme.css`:
143
+ ```css
144
+ --color-mycolor: #hexvalue;
145
+ ```
146
+ 2. Run `npm run build` — the color will auto-appear in `llms.md`
146
147
 
147
- ```tsx
148
- import {Button, Card, Input} from '@lukeashford/aurelius'
149
-
150
- function LoginForm() {
151
- return (
152
- <Card variant="featured" className="p-8 max-w-sm mx-auto">
153
- <h2 className="text-gold text-2xl mb-6">Sign In</h2>
154
- <Input placeholder="email@example.com"/>
155
- <Button variant="primary" className="w-full mt-4">
156
- Enter
157
- </Button>
158
- </Card>
159
- )
160
- }
161
- ```
148
+ ### Update component documentation
149
+
150
+ 1. Edit JSDoc comments in the component file
151
+ 2. Run `npm run build` to regenerate `llms.md`
152
+ 3. Commit both files