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 `