diff --git a/src/app.css b/src/app.css
index 2963384..89a56e5 100644
--- a/src/app.css
+++ b/src/app.css
@@ -156,43 +156,67 @@
/* === HEADINGS === */
/* Base heading styles - gray-900 (light) / gray-100 (dark) for high contrast */
- h1, h2, h3, h4, h5, h6,
- h1.h-leather, h2.h-leather, h3.h-leather,
- h4.h-leather, h5.h-leather, h6.h-leather {
+ h1,
+ h2,
+ h3,
+ h4,
+ h5,
+ h6,
+ h1.h-leather,
+ h2.h-leather,
+ h3.h-leather,
+ h4.h-leather,
+ h5.h-leather,
+ h6.h-leather {
@apply text-gray-900 dark:text-gray-100;
}
/* Heading sizes and weights */
- h1, h1.h-leather {
+ h1,
+ h1.h-leather {
@apply text-4xl font-bold;
}
- h2, h2.h-leather {
+ h2,
+ h2.h-leather {
@apply text-3xl font-bold;
}
- h3, h3.h-leather {
+ h3,
+ h3.h-leather {
@apply text-2xl font-bold;
}
- h4, h4.h-leather {
+ h4,
+ h4.h-leather {
@apply text-xl font-bold;
}
- h5, h5.h-leather {
+ h5,
+ h5.h-leather {
@apply text-lg font-semibold;
}
- h6, h6.h-leather {
+ h6,
+ h6.h-leather {
@apply text-base font-semibold;
}
/* Heading links - primary-600 (light) / primary-400 (dark) for hover */
- h1 a, h2 a, h3 a, h4 a, h5 a, h6 a,
- h1.h-leather a, h2.h-leather a, h3.h-leather a,
- h4.h-leather a, h5.h-leather a, h6.h-leather a {
- @apply text-gray-900 dark:text-gray-100
- hover:text-primary-600 dark:hover:text-primary-400;
+ h1 a,
+ h2 a,
+ h3 a,
+ h4 a,
+ h5 a,
+ h6 a,
+ h1.h-leather a,
+ h2.h-leather a,
+ h3.h-leather a,
+ h4.h-leather a,
+ h5.h-leather a,
+ h6.h-leather a {
+ @apply text-gray-900 dark:text-gray-100 hover:text-primary-600
+ dark:hover:text-primary-400;
}
/* === LEATHER COMPONENTS === */
@@ -248,8 +272,7 @@
div.note-leather,
p.note-leather,
section.note-leather {
- @apply text-gray-900 dark:text-gray-100
- p-2 rounded;
+ @apply text-gray-900 dark:text-gray-100 p-2 rounded;
}
.edit div.note-leather:hover:not(:has(.note-leather:hover)),
@@ -407,14 +430,14 @@
/* Lists */
.ol-leather li a,
.ul-leather li a {
- @apply text-gray-900 dark:text-gray-100
- hover:text-primary-600 dark:hover:text-primary-400;
+ @apply text-gray-900 dark:text-gray-100 hover:text-primary-600
+ dark:hover:text-primary-400;
}
/* Links - consistent hover colors */
.link {
- @apply underline cursor-pointer
- hover:text-primary-600 dark:hover:text-primary-400;
+ @apply underline cursor-pointer hover:text-primary-600
+ dark:hover:text-primary-400;
}
.npub-badge {
@@ -506,8 +529,8 @@
/* All links - consistent hover behavior */
a {
- @apply underline cursor-pointer
- hover:text-primary-600 dark:hover:text-primary-400;
+ @apply underline cursor-pointer hover:text-primary-600
+ dark:hover:text-primary-400;
}
.imageblock {
@@ -694,10 +717,9 @@
}
}
- .icon-wiki {
- font-size: 20px;
- line-height: 20px;
- vertical-align: text-bottom;
- font-weight: 500;
- }
+.icon-wiki {
+ font-size: 20px;
+ line-height: 20px;
+ vertical-align: text-bottom;
+ font-weight: 500;
}
diff --git a/src/lib/a/AGENTS.md b/src/lib/a/AGENTS.md
index e34db9c..34e1425 100644
--- a/src/lib/a/AGENTS.md
+++ b/src/lib/a/AGENTS.md
@@ -1,23 +1,30 @@
# Alexandria Component Library - AI Agent Guide
-**Version:** 1.0.0
+**Version:** 1.0.0\
**Last Updated:** October 4, 2025
-This guide provides comprehensive instructions for AI agents working with the Alexandria UI component library. Following these guidelines ensures consistency, maintainability, and proper integration with the existing codebase.
+This guide provides comprehensive instructions for AI agents working with the
+Alexandria UI component library. Following these guidelines ensures consistency,
+maintainability, and proper integration with the existing codebase.
---
## Core Principles
### 1. Always Check Before Creating
+
Before creating any new UI component, **you must**:
+
1. Search the existing component library in `src/lib/a/`
2. Review `alexandria-components.json` for available components
3. Check if an existing component can be reused or extended
4. Only create new components when absolutely necessary
### 2. Use alexandria-components.json as Your Reference
-The `alexandria-components.json` file is the **single source of truth** for all available components. It contains:
+
+The `alexandria-components.json` file is the **single source of truth** for all
+available components. It contains:
+
- Complete component inventory (18 components across 5 categories)
- Full prop definitions with types and defaults
- Usage examples and patterns
@@ -26,13 +33,16 @@ The `alexandria-components.json` file is the **single source of truth** for all
**Always consult this file first** when selecting components.
### 3. Maintain TSDoc Documentation Standards
-All components use **TSDoc format** for documentation. You must maintain this standard when creating or modifying components.
+
+All components use **TSDoc format** for documentation. You must maintain this
+standard when creating or modifying components.
---
## Component Inventory
### Available Categories
+
1. **Primitives** (8 components) - Basic UI building blocks
2. **Navigation** (2 components) - App navigation elements
3. **Forms** (4 components) - Input and editing interfaces
@@ -44,7 +54,9 @@ All components use **TSDoc format** for documentation. You must maintain this st
## Component Selection Workflow
### Step 1: Identify the Need
+
Determine what UI functionality is required:
+
- User input? → Check **Forms** category
- Display content? → Check **Cards** category
- Navigation? → Check **Navigation** category
@@ -59,7 +71,9 @@ For example: Finding a component for user profiles
- Result: AProfilePreview and ANostrUser are available
### Step 3: Review Component Props
+
Check the component's props in `alexandria-components.json`:
+
```json
{
"name": "AEventPreview",
@@ -82,6 +96,7 @@ Check the component's props in `alexandria-components.json`:
```
### Step 4: Review Examples
+
Check the `examples` array in `alexandria-components.json` for usage patterns.
---
@@ -111,7 +126,6 @@ Every component **must** include TSDoc comments following this exact format:
*
* ```
*
- *
* @features
* - Feature 1
* - Feature 2
@@ -126,24 +140,25 @@ Every component **must** include TSDoc comments following this exact format:
### TSDoc Tags Reference
-| Tag | Purpose | Required | Example |
-|-----|---------|----------|---------|
-| `@fileoverview` | Component name and description | ✅ Yes | `@fileoverview AAlert Component - Alexandria` |
-| `@component` | Marks file as Svelte component | ✅ Yes | `@component` |
-| `@category` | Component category | ✅ Yes | `@category Primitives` |
-| `@prop` | Define component properties | ✅ Yes | `@prop {string} [color] - Alert color theme` |
-| `@example` | Usage examples with code | ✅ Yes | See format above |
-| `@features` | List key functionality | ✅ Yes | `- Responsive layout` |
-| `@accessibility` | Accessibility notes | ✅ Yes | `- ARIA compliant` |
-| `@since` | Version introduced | ⚠️ Optional | `@since 1.0.0` |
+| Tag | Purpose | Required | Example |
+| ---------------- | ------------------------------ | ----------- | --------------------------------------------- |
+| `@fileoverview` | Component name and description | ✅ Yes | `@fileoverview AAlert Component - Alexandria` |
+| `@component` | Marks file as Svelte component | ✅ Yes | `@component` |
+| `@category` | Component category | ✅ Yes | `@category Primitives` |
+| `@prop` | Define component properties | ✅ Yes | `@prop {string} [color] - Alert color theme` |
+| `@example` | Usage examples with code | ✅ Yes | See format above |
+| `@features` | List key functionality | ✅ Yes | `- Responsive layout` |
+| `@accessibility` | Accessibility notes | ✅ Yes | `- ARIA compliant` |
+| `@since` | Version introduced | ⚠️ Optional | `@since 1.0.0` |
---
## Component Import Patterns
### Import
+
```typescript
-import { AAlert, AEventPreview, AMarkupForm } from '$lib/a';
+import { AAlert, AEventPreview, AMarkupForm } from "$lib/a";
```
---
@@ -153,12 +168,14 @@ import { AAlert, AEventPreview, AMarkupForm } from '$lib/a';
### When to Create a New Component
**DO create a new component when:**
+
- No existing component provides the required functionality
- The component will be reused in 3+ places
- It represents a distinct, standalone UI pattern
- It follows the Alexandria design system
**DON'T create a new component when:**
+
- An existing component can be configured to meet needs
- It's only used once (keep in parent component)
- It's too generic (use Flowbite components directly)
@@ -171,7 +188,8 @@ import { AAlert, AEventPreview, AMarkupForm } from '$lib/a';
- [ ] **Name** following convention: `A[ComponentName].svelte`
- [ ] **Add TSDoc** documentation following standard format
- [ ] **Create** component file in correct category folder
-- [ ] **Add styles** to appropriate `/src/styles/a/` CSS file (or create new file if needed)
+- [ ] **Add styles** to appropriate `/src/styles/a/` CSS file (or create new
+ file if needed)
- [ ] **Import new CSS file** in `app.css` if created
- [ ] **Export** component in `index.ts`
- [ ] **Update** `alexandria-components.json` (run parse script)
@@ -227,7 +245,9 @@ let {
## Updating alexandria-components.json
### When to Update
+
You **must** update `alexandria-components.json` whenever:
+
- A new component is created
- Component props are added, modified, or removed
- Component examples are updated
@@ -246,12 +266,15 @@ You **must** update `alexandria-components.json` whenever:
4. **Commit** both the component file and updated JSON
### Parser Script Location
+
- **File:** `src/lib/a/parse-components.js`
- **Purpose:** Extracts TSDoc from all `.svelte` files in the library
- **Output:** `alexandria-components.json`
### Manual Updates (When Necessary)
+
If the parser doesn't capture something correctly:
+
1. First, try to fix the TSDoc format
2. Re-run the parser
3. Only manually edit JSON as last resort
@@ -262,7 +285,9 @@ If the parser doesn't capture something correctly:
## Design System Integration
### Theme Compatibility
+
All Alexandria components support:
+
- Light and dark themes
- "Leather" aesthetic (warm browns, tans)
- Flowbite-based styling
@@ -271,6 +296,7 @@ All Alexandria components support:
### Styling Guidelines
**DO:**
+
- Use Tailwind CSS classes
- Leverage Flowbite Svelte components as base
- Follow existing color patterns in library
@@ -278,12 +304,14 @@ All Alexandria components support:
- Test in both light and dark modes
**DON'T:**
+
- Add arbitrary custom CSS without justification
- Override Flowbite's accessibility features
- Hard-code colors (use theme tokens)
- Create layout inconsistencies
### Component Styling Pattern
+
```svelte
@@ -297,9 +325,11 @@ All Alexandria components support:
### **Mandatory Styling Rules**
-⚠️ **ALL custom styles for Alexandria components MUST go in the `/src/styles/a/` folder.**
+⚠️ **ALL custom styles for Alexandria components MUST go in the `/src/styles/a/`
+folder.**
-**DO NOT add `