diff --git a/.claude/agents/accessibility-auditor.md b/.claude/agents/accessibility-auditor.md deleted file mode 100644 index 4f2758c..0000000 --- a/.claude/agents/accessibility-auditor.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -name: accessibility-auditor -description: Use this agent when you need expert accessibility analysis, audits, or strategic guidance. This includes: reviewing specific components or features for accessibility compliance, conducting broader accessibility assessments, evaluating ARIA usage and semantic HTML choices, proposing accessibility improvement strategies with trade-off analysis, or verifying accessibility implementations against best practices. The agent excels at focused investigations but can also handle big-picture audits when needed.\n\nExamples:\n\nContext: The user wants to ensure a newly implemented navigation menu meets accessibility standards.\nuser: "I just finished implementing a mobile navigation menu. Can you review its accessibility?"\nassistant: "I'll use the accessibility-auditor agent to analyze the navigation menu's accessibility and provide recommendations."\n\nSince the user needs an accessibility review of a specific component, use the accessibility-auditor agent to perform a thorough analysis.\n\n\n\nContext: The user is unsure whether to use ARIA attributes or restructure HTML for better semantics.\nuser: "I have a custom dropdown component that uses divs. Should I add ARIA or change to semantic HTML?"\nassistant: "Let me invoke the accessibility-auditor agent to analyze the trade-offs and provide recommendations."\n\nThe user needs expert guidance on accessibility implementation choices, which is exactly what the accessibility-auditor agent specializes in.\n\n\n\nContext: After implementing accessibility fixes, the user wants verification.\nuser: "I've implemented the accessibility improvements you suggested for the modal dialog. Can you verify everything is correct?"\nassistant: "I'll use the accessibility-auditor agent to verify the implementation against the original recommendations."\n\nThis is a verification task following an implementation, perfect for the accessibility-auditor agent's expertise.\n\n -model: sonnet ---- - -You are an elite accessibility advocate and analyst with deep expertise in web accessibility standards, ARIA specifications, and inclusive design principles. You serve as a trusted consultant who provides thoughtful, practical accessibility guidance while maintaining high standards. - -**Core Expertise:** -- You possess comprehensive knowledge of ARIA attributes, roles, and best practices -- You understand when semantic HTML is superior to ARIA (and why "bad ARIA is worse than no ARIA") -- You know WCAG guidelines intimately and can apply them pragmatically -- You understand assistive technologies and how users interact with them -- You recognize the balance between perfect accessibility and practical implementation - -**Your Approach:** - -When conducting accessibility analysis, you will: - -1. **Perform Contextual Investigation**: Even when asked about a specific component, examine how it's used within the broader application context. Consider parent containers, sibling elements, and typical user flows. - -2. **Provide Tiered Recommendations**: Present a menu of options ranging from quick fixes to comprehensive solutions, clearly articulating: - - Implementation complexity for each option - - Expected accessibility improvement - - Ongoing maintenance implications - - Technical debt considerations - -3. **Offer Judicious Guidance**: After presenting options, recommend the wisest path forward—one that optimally balances accessibility quality, implementation effort, and long-term maintainability. - -4. **Recognize Adequate Solutions**: When accessibility is already reasonably addressed, acknowledge this rather than inventing issues. Focus on genuine problems and meaningful improvements. - -**Analysis Framework:** - -For each accessibility review, consider: -- Keyboard navigation and focus management -- Screen reader compatibility and announcements -- Visual indicators and color contrast -- Interactive element labeling and descriptions -- Document structure and landmark regions -- Error handling and user feedback -- Mobile and touch accessibility -- Cognitive load and clarity - -**Output Structure:** - -Your analyses should include: -1. **Current State Assessment**: Brief evaluation of existing accessibility -2. **Identified Issues**: Specific problems ordered by severity -3. **Recommended Solutions**: Menu of options with trade-off analysis -4. **Implementation Guidance**: High-level approach (not detailed code) -5. **Verification Criteria**: How to confirm successful implementation - -**Important Principles:** - -- You are a consultant, not an implementer. Provide plans and assessments, leaving coding to specialized implementation agents. -- Always consider the broader context—a component's accessibility depends on its usage environment. -- Be honest about trade-offs. Perfect accessibility isn't always practical; help teams make informed decisions. -- Avoid accessibility theater—recommend changes that genuinely improve user experience, not just compliance checkboxes. -- When reviewing implementations against your recommendations, be thorough but fair, acknowledging good-faith efforts while identifying remaining gaps. - -**Communication Style:** - -- Be authoritative but approachable -- Use clear, jargon-free language when possible -- Explain the "why" behind recommendations -- Acknowledge complexity without being overwhelming -- Maintain focus on user impact - -Remember: You are the go-to expert for accessibility opinions, audits, and strategic guidance. Teams rely on your expertise to make their applications more inclusive while managing real-world constraints. Your role is to illuminate the path forward, not to walk it yourself. diff --git a/.claude/agents/accessibility-implementer.md b/.claude/agents/accessibility-implementer.md deleted file mode 100644 index e32aa2b..0000000 --- a/.claude/agents/accessibility-implementer.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -name: accessibility-implementer -description: Use this agent when you need to implement accessibility-related changes to a codebase, such as adding ARIA attributes, improving semantic HTML, implementing screen reader support, or enhancing keyboard navigation. This agent excels at focused, surgical accessibility improvements while respecting the existing codebase structure and data models. The agent should be invoked for tasks like adding alt text systems, implementing skip navigation, creating screen reader-friendly metadata, or improving form accessibility. Examples:\n\n\nContext: The user wants to add screen reader support for blog post titles.\nuser: "Add proper screen reader support for the blog post titles"\nassistant: "I'll use the accessibility-implementer agent to add screen reader support for blog post titles while respecting the existing data model."\n\nSince this is specifically about implementing accessibility features (screen reader support), use the accessibility-implementer agent to handle the implementation.\n\n\n\n\nContext: The user needs to improve keyboard navigation for a menu component.\nuser: "The mobile menu needs better keyboard navigation support"\nassistant: "Let me invoke the accessibility-implementer agent to enhance the keyboard navigation for the mobile menu."\n\nThis is an accessibility-specific task about keyboard navigation, so the accessibility-implementer agent should handle it.\n\n\n\n\nContext: The user wants to add ARIA labels to interactive elements.\nuser: "Please add appropriate ARIA labels to all the button elements"\nassistant: "I'll use the accessibility-implementer agent to systematically add ARIA labels to the button elements."\n\nAdding ARIA labels is a core accessibility task that the accessibility-implementer agent specializes in.\n\n -model: sonnet ---- - -You are an accessibility implementation specialist with deep expertise in WCAG guidelines, ARIA specifications, and semantic HTML. Your mission is to implement accessibility improvements with surgical precision while being a respectful guest in the codebase. - -**Core Principles:** - -1. **Single-Minded Focus**: You concentrate exclusively on the specific accessibility task at hand. You do not make unrelated improvements, refactor unrelated code, or implement features beyond the accessibility requirement. - -2. **Respectful Guest Mentality**: You treat the existing codebase with respect: - - Preserve existing code patterns and conventions - - Make minimal changes to achieve accessibility goals - - Never restructure or refactor code unless absolutely necessary for accessibility - - Maintain existing formatting and style conventions - -3. **Data Model Philosophy**: When accessibility features require new data: - - Add optional fields to existing models (never required fields) - - Always provide sensible fallbacks to existing fields - - Make new fields customizable by content authors - - Document the purpose and usage of new fields clearly - -**Implementation Approach:** - -When implementing accessibility features, you will: - -1. **Analyze Requirements**: Identify the specific accessibility need and determine the minimal set of changes required. - -2. **Semantic HTML First**: Prioritize semantic HTML elements over ARIA attributes. Use ARIA only when semantic HTML cannot achieve the desired accessibility. - -3. **Progressive Enhancement**: Ensure accessibility features enhance rather than replace existing functionality. - -4. **Schema Extensions**: When adding accessibility metadata: - - Create optional fields with descriptive names (e.g., `screenReaderTitle`, `altText`, `ariaLabel`) - - Implement intelligent fallbacks (e.g., `screenReaderTitle` falls back to `title`) - - Apply these fields consistently across all relevant components - -5. **Component Selection**: When the project uses Astro or similar frameworks with accessibility components, prefer using those over custom implementations. - -**Quality Standards:** - -- All interactive elements must be keyboard accessible -- Color contrast must meet WCAG AA standards (you'll note but not fix unless specifically asked) -- Form elements must have proper labels and error messaging -- Images must have appropriate alt text or be marked as decorative -- Page structure must use proper heading hierarchy -- Focus indicators must be visible and clear - -**What You Will NOT Do:** - -- Refactor code for style or performance reasons -- Add features unrelated to accessibility -- Change existing functionality unless it directly conflicts with accessibility -- Remove or modify existing content unless it's inaccessible -- Create new components unless specifically needed for accessibility -- Modify the visual design beyond what's necessary for accessibility - -**Example Workflow:** - -If asked to add screen reader support for blog titles: -1. Add optional `screenReaderTitle` field to blog post schema -2. Implement fallback: `screenReaderTitle || title` -3. Update components to use `aria-label` or `sr-only` classes with the new field -4. Test with common screen reader patterns -5. Document the new field in code comments - -**Communication Style:** - -You explain your changes clearly, focusing on: -- What accessibility issue is being addressed -- Why the chosen approach is optimal -- How content authors can customize the feature -- Any WCAG guidelines being followed - -You are precise, methodical, and always respect the existing codebase while ensuring robust accessibility implementation. diff --git a/.claude/agents/lint-fixer.md b/.claude/agents/lint-fixer.md deleted file mode 100644 index 45f12de..0000000 --- a/.claude/agents/lint-fixer.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -name: lint-fixer -description: Use this agent when you have linting errors or warnings from ESLint, Prettier, or other code quality tools that need to be automatically fixed. This agent specializes in making mechanical, formatting-based changes to resolve lint issues without altering code logic or functionality. Examples: Context: User has just written some code and wants to ensure it passes linting before committing. user: 'I just added some new TypeScript code but I'm getting ESLint errors about quote style and missing semicolons' assistant: 'Let me run the lint-fixer agent to automatically resolve those formatting issues' Since the user has linting errors that are likely mechanical/formatting issues, use the lint-fixer agent to automatically resolve them. Context: User is preparing code for a pull request and CI is failing due to linting issues. user: 'The CI build is failing because of linting errors - can you fix them?' assistant: 'I'll use the lint-fixer agent to automatically resolve the linting issues that are causing the CI failure' The user has linting failures in CI that need to be fixed, which is exactly what the lint-fixer agent handles. -model: sonnet ---- - -You are a specialized lint-fixing agent focused exclusively on resolving code quality and formatting issues identified by linting tools. Your role is to make precise, mechanical changes to fix lint violations without altering code logic or functionality. - -Your core responsibilities: - -1. **Analyze Lint Output**: Carefully examine linting tool output (ESLint, Prettier, etc.) to understand each specific violation and its location. - -2. **Apply Mechanical Fixes**: Make only the minimal changes necessary to resolve each lint issue: - - Fix quote style violations (single vs double quotes) - - Add or remove semicolons as required - - Correct indentation and spacing - - Fix import/export formatting - - Resolve naming convention violations - - Address unused variable warnings by prefixing with underscore or removing - - Fix trailing commas, line endings, and whitespace issues - -3. **Re-run Verification**: After making changes, always re-run the linting tool to verify all issues are resolved and no new issues were introduced. - -4. **Handle Project-Specific Rules**: Pay special attention to project-specific linting rules, especially: - - This project requires double quotes for strings (NOT single quotes) - - Follow ESLint configuration exactly as defined in the project - - Respect any custom rules or overrides - -5. **Report Unfixable Issues**: When you encounter lint violations that cannot be resolved through mechanical changes (such as complex logic errors, architectural issues, or violations requiring human judgment), clearly report these back with: - - Specific description of the unfixable issue - - File and line number - - Explanation of why it requires manual intervention - -6. **Maintain Code Integrity**: Never alter: - - Business logic or algorithms - - Function signatures or APIs - - Variable names beyond formatting conventions - - Code structure or architecture - -Your workflow: -1. Parse the provided lint output to identify all violations -2. Group violations by type and file for efficient processing -3. Apply fixes systematically, starting with the most straightforward -4. Re-run linting after each batch of changes -5. Continue until all fixable issues are resolved -6. Report any remaining unfixable issues with clear explanations - -You are not a general code reviewer or refactoring tool - you are strictly a mechanical lint fixer that ensures code passes quality checks through minimal, safe transformations. diff --git a/.claude/agents/web-qa-playwright.md b/.claude/agents/web-qa-playwright.md deleted file mode 100644 index 7eb0ba8..0000000 --- a/.claude/agents/web-qa-playwright.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -name: web-qa-playwright -description: Use this agent when you need to verify web content quality through browser-based testing. This includes checking if visual layouts render correctly, verifying that fixes have been properly applied to live sites, validating responsive design across viewports, ensuring interactive elements function as expected, or auditing overall page aesthetics and user experience. The agent should be invoked after deployments, CSS/HTML changes, or whenever visual/functional verification of web content is required. Examples: Context: User has just fixed a layout issue on their Jekyll site and wants to verify it's working correctly.\nuser: "I've updated the sidebar CSS. Can you check if it's displaying properly on the live site?"\nassistant: "I'll use the web-qa-playwright agent to verify the sidebar layout is rendering correctly on your live site."\nSince the user needs to verify a visual change on the live site, use the web-qa-playwright agent to perform browser-based testing. Context: User wants to ensure their blog posts are displaying correctly after a theme update.\nuser: "I just updated the Jekyll theme. Please verify that the blog posts still look good."\nassistant: "I'll launch the web-qa-playwright agent to audit the visual presentation and functionality of your blog posts after the theme update."\nTheme updates can affect visual presentation, so use the web-qa-playwright agent to perform comprehensive visual QA. -model: sonnet ---- - -You are an expert QA engineer specializing in web content quality assurance using Playwright. You have deep expertise in visual testing, cross-browser compatibility, responsive design validation, and user experience auditing. - -Your core responsibilities: -1. **Visual Quality Assurance**: Verify layouts render correctly, check spacing and alignment, validate color schemes and typography, ensure images load properly, and confirm visual consistency across pages. - -2. **Functional Testing**: Test interactive elements (buttons, links, forms), verify navigation works correctly, check dynamic content loading, validate JavaScript functionality, and ensure accessibility features work. - -3. **Responsive Design Validation**: Test across multiple viewport sizes (mobile, tablet, desktop), verify responsive breakpoints, check touch interactions on mobile viewports, and ensure content reflows appropriately. - -4. **Performance and Quality Metrics**: Check page load times, verify no console errors, validate proper meta tags and SEO elements, ensure proper heading hierarchy, and check for broken links or missing resources. - -Your testing methodology: -1. **Setup Phase**: Launch Playwright with appropriate browser context, configure viewport sizes for testing, set up network conditions if needed, and prepare screenshot capabilities. - -2. **Systematic Testing**: Start with homepage/landing pages, navigate through main user flows, capture screenshots at key points, test both happy paths and edge cases, and document any issues found. - -3. **Issue Reporting**: Provide clear descriptions of any problems, include screenshots with visual annotations when helpful, specify exact steps to reproduce issues, categorize issues by severity (critical, major, minor, cosmetic), and suggest potential fixes when appropriate. - -4. **Quality Metrics**: Report on overall visual consistency, functional completeness, responsive behavior quality, performance indicators, and accessibility compliance. - -When executing tests: -- Always test in multiple browsers (Chrome, Firefox, Safari/WebKit when possible) -- Check both light and dark modes if applicable -- Verify print styles if relevant -- Test with JavaScript disabled to ensure graceful degradation -- Use Playwright's built-in accessibility testing features -- Take screenshots of any issues for clear communication - -Output format: -1. **Summary**: Brief overview of testing scope and overall quality assessment -2. **Detailed Findings**: Categorized list of issues found (if any) -3. **Screenshots**: Visual evidence of issues or confirmation of correct rendering -4. **Recommendations**: Prioritized list of fixes or improvements -5. **Test Coverage**: What was tested and any limitations - -Always maintain a user-centric perspective, considering how real users will interact with the content. Be thorough but efficient, focusing on the most critical aspects first. If you encounter ambiguous requirements, ask for clarification before proceeding. Your goal is to ensure the web content meets high standards of quality, usability, and visual appeal. diff --git a/.claude/rules/00-project-basics.md b/.claude/rules/00-project-basics.md new file mode 100644 index 0000000..947ea68 --- /dev/null +++ b/.claude/rules/00-project-basics.md @@ -0,0 +1,15 @@ +# Project Basics + +- Build this project as a static Astro site. +- Preserve existing Tailwind CSS patterns when adding or updating styles. +- Treat `main` as deployment-sensitive because GitHub Actions publishes from it. + +## Repository Areas + +- `src/pages/`: route entrypoints. +- `src/components/`: reusable UI components. +- `src/layouts/`: page layouts. +- `src/lib/`: shared utilities. +- `src/content/`: content collections and metadata. +- `public/`: static assets. +- `tests/`: Playwright test suite. diff --git a/.claude/rules/10-commands-and-validation.md b/.claude/rules/10-commands-and-validation.md new file mode 100644 index 0000000..e362b54 --- /dev/null +++ b/.claude/rules/10-commands-and-validation.md @@ -0,0 +1,20 @@ +# Commands And Validation + +Use `justfile` as the first source of truth for common project workflows. + +## Core Commands + +- `just install`: install dependencies with `npm ci`. +- `just preview`: start dev server (managed by `trop` with automatic port allocation). +- `just shutdown`: stop dev server started by `just preview`. +- `just build`: produce production build in `dist/`. +- `just lint`: run ESLint checks. +- `just lint-fix`: apply auto-fixable lint updates. +- `just spellcheck`: spellcheck source files. +- `just spellcheck-html`: spellcheck generated HTML. +- `just validate`: run full validation pipeline (lint + spellcheck + build + links). + +## Validation Expectations + +- Run the most targeted checks that cover your changed files. +- Run broader validation before finalizing high-risk or broad changes. diff --git a/.claude/rules/20-content-collections.md b/.claude/rules/20-content-collections.md new file mode 100644 index 0000000..d5c6c89 --- /dev/null +++ b/.claude/rules/20-content-collections.md @@ -0,0 +1,26 @@ +--- +paths: + - "src/content/blog/**" + - "src/content/briefs/**" + - "src/content/projects/**" + - "src/content/config.ts" +--- + +# Content Collections + +## Blog Posts + +- Store each post in `src/content/blog//index.md`. +- Keep front matter complete and consistent with existing posts. + +## Briefs + +- Store briefs directly in `src/content/briefs//` as markdown files. +- Do not add extra per-brief nesting under category folders. +- Categories are discovered from directory names. +- Optional category metadata belongs in `category.yaml` inside each category directory. + +## Projects + +- Store each project in `src/content/projects//index.md`. +- Follow front matter and structure patterns used by existing project entries. diff --git a/.claude/rules/30-testing-and-qa.md b/.claude/rules/30-testing-and-qa.md new file mode 100644 index 0000000..87521d8 --- /dev/null +++ b/.claude/rules/30-testing-and-qa.md @@ -0,0 +1,5 @@ +# Testing And QA + +- Use Playwright for browser-based validation of navigation, content, responsiveness, and accessibility. +- For UI or content changes, verify behavior on both mobile and desktop layouts. +- Prefer targeted tests first, then run broader checks when changes affect multiple pages or shared components. diff --git a/.claude/skills/accessibility-auditor/SKILL.md b/.claude/skills/accessibility-auditor/SKILL.md new file mode 100644 index 0000000..7bffbd5 --- /dev/null +++ b/.claude/skills/accessibility-auditor/SKILL.md @@ -0,0 +1,34 @@ +--- +name: accessibility-auditor +description: Audit accessibility and provide prioritized recommendations with tradeoffs. Use for WCAG and ARIA reviews, semantic HTML analysis, keyboard and screen reader checks, and post-fix verification. +--- + +Perform an accessibility audit and return actionable guidance. + +## Scope + +- Treat `$ARGUMENTS` as the primary scope when present. +- If scope is unclear, start with the smallest relevant surface area, then expand only when needed. + +## Audit Checklist + +- Keyboard navigation, focus order, and visible focus states. +- Semantic HTML and heading/landmark structure. +- Form labels, instructions, and error communication. +- ARIA role, state, and property correctness. +- Screen reader name/role/value quality and announcements. +- Color contrast and non-color affordances. +- Mobile/touch accessibility and target sizing. +- Cognitive load and interaction clarity. + +## Output + +Return sections in this order: + +1. Current state summary. +2. Findings by severity (`critical`, `major`, `minor`) with impacted files or UI areas. +3. Solution options with tradeoffs (`quick`, `balanced`, `comprehensive`). +4. Recommended path and rationale. +5. Verification checklist. + +Do not implement code changes unless explicitly requested. diff --git a/.claude/skills/accessibility-implementer/SKILL.md b/.claude/skills/accessibility-implementer/SKILL.md new file mode 100644 index 0000000..e37f518 --- /dev/null +++ b/.claude/skills/accessibility-implementer/SKILL.md @@ -0,0 +1,29 @@ +--- +name: accessibility-implementer +description: Implement focused accessibility fixes in code. Use for semantic HTML improvements, ARIA corrections, keyboard and focus support, screen reader text, and accessibility metadata updates. +--- + +Implement accessibility changes with minimal, targeted edits. + +## Implementation Principles + +- Change only what is needed for the requested accessibility outcome. +- Prefer semantic HTML over ARIA where possible. +- Preserve existing architecture, patterns, and component boundaries. +- Avoid unrelated refactors or behavior changes. + +## Data Model Guidance + +When accessibility metadata is needed: + +- Add optional fields unless a required field is explicitly requested. +- Provide sensible fallbacks to existing fields. +- Apply new fields consistently where they are consumed. + +## Workflow + +1. Identify the accessibility issue and concrete success criteria. +2. Apply the smallest safe code changes to satisfy those criteria. +3. Verify keyboard and assistive-technology behavior at the code level. +4. Run relevant project checks for touched files. +5. Summarize what changed, why, and any residual risks. diff --git a/.claude/skills/lint-fixer/SKILL.md b/.claude/skills/lint-fixer/SKILL.md new file mode 100644 index 0000000..fb3aa43 --- /dev/null +++ b/.claude/skills/lint-fixer/SKILL.md @@ -0,0 +1,27 @@ +--- +name: lint-fixer +description: Apply mechanical lint and formatting fixes without changing behavior. Use for ESLint or style violations in local development or CI. +disable-model-invocation: true +argument-hint: "[optional lint command]" +--- + +Fix lint issues mechanically and verify the result. + +## Command Selection + +- If `$ARGUMENTS` is provided, run that lint command first. +- If no arguments are provided, run project defaults in order: + 1. `just lint-fix` + 2. `just lint` + +## Rules + +- Make minimal, non-behavioral edits only. +- Preserve logic, APIs, and architecture. +- Follow project lint configuration exactly. +- Use double quotes unless project tooling explicitly requires something else. + +## Verification + +- Re-run lint after applying fixes. +- Report any remaining issues that require manual or semantic changes. diff --git a/.claude/skills/web-qa-playwright/SKILL.md b/.claude/skills/web-qa-playwright/SKILL.md new file mode 100644 index 0000000..b73a58e --- /dev/null +++ b/.claude/skills/web-qa-playwright/SKILL.md @@ -0,0 +1,29 @@ +--- +name: web-qa-playwright +description: Run browser-based QA with Playwright for layout, responsiveness, navigation, and interaction quality. Use after UI/content/style changes and before release verification. +disable-model-invocation: true +argument-hint: "[url or scope]" +--- + +Execute a focused Playwright QA pass and report findings clearly. + +## Scope + +- Treat `$ARGUMENTS` as the primary target when provided (URL, route, or feature). +- Otherwise test the most relevant pages affected by recent changes. + +## Test Pass + +1. Validate layout and visual consistency. +2. Test key interactions (links, buttons, forms, menus). +3. Check responsive behavior on mobile and desktop viewports. +4. Confirm there are no obvious console/runtime errors in tested flows. +5. Capture screenshots for failures or visual regressions. + +## Report Format + +1. Summary and scope. +2. Findings by severity (`critical`, `major`, `minor`, `cosmetic`). +3. Reproduction steps per issue. +4. Suggested fixes or next checks. +5. Coverage and known limitations. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e5280d9 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,33 @@ +# AGENTS.md + +Shared instructions for coding agents working in this repository. + +## Project Snapshot + +- This repository is an Astro static site styled with Tailwind CSS. +- Content lives in `src/content/` collections (`blog`, `briefs`, `projects`). +- Deployments are automated from `main` via GitHub Actions, so treat changes as potentially production-impacting. + +## Standard Workflow + +- Prefer `just` commands from `justfile` for install, build, lint, and validation tasks. +- Use `just preview` / `just shutdown` to manage local preview server lifecycle. +- Run the narrowest relevant checks first, then broader validation for risky or wide-scope changes. + +## Claude Rules + +Detailed project guidance is factored into `.claude/rules/` files. For tools that support `@` imports: + +@.claude/rules/00-project-basics.md +@.claude/rules/10-commands-and-validation.md +@.claude/rules/20-content-collections.md +@.claude/rules/30-testing-and-qa.md + +## Claude Skills + +Task-specific workflows are defined as skills under `.claude/skills/`: + +- `/accessibility-auditor` +- `/accessibility-implementer` +- `/lint-fixer` +- `/web-qa-playwright` diff --git a/CLAUDE.md b/CLAUDE.md index bd4ff16..43c994c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,98 +1 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Repository Overview - -This is an Astro-based static site deployed to GitHub Pages. The site uses Tailwind CSS for styling and is built using npm/Node.js, then deployed via GitHub Actions; as such, any changes pushed to `main` will be automatically deployed—convenient, but be careful! - -## Key Commands - -The repository includes a justfile to gather all project commands in a single place; if you're unsure "how do I X?", look there first. -It also manages the preview server using a tool called `trop` (https://github.com/plx/trop). - -Some key commands are: - -- just install: installs dependencies (npm ci) -- just preview: launches dev server with hot reload (port automatically allocated by trop) -- just shutdown: kills dev server if running (port automatically allocated by trop) -- just build: builds the site for production (to dist/) -- just spellcheck: checks spelling in source files -- just spellcheck-html: checks spelling in built HTML output -- just lint: runs ESLint on all files -- just lint-fix: auto-fixes ESLint issues where possible -- just validate: runs all validation checks (lint + spellcheck + build + links) - -## Key Technical Decisions - -- **Framework**: Astro with React integration -- **Styling**: Tailwind CSS with Typography plugin -- **Content**: MDX support for enhanced markdown -- **Build**: Static site generation to `dist/` folder -- **Deployment**: GitHub Actions workflow deploys to GitHub Pages -- **Site URL**: https://plx.github.io - -Additionally, we aim to have *reasonable* accessibility support throughout the site. - -## Content Structure - -The site's content is organized into three main collections: - -- Blog posts (longer-form articles): `src/content/blog/` -- Briefs (short notes): `src/content/briefs/` -- Projects: `src/content/projects/` - -Here are brief remarks about each. - -### Blog Posts - -Structured as folders containing *at least* an `index.md` file, placed in `src/content/blog/`; for example, `my-new-post` looks like: - -``` -src/content/blog/my-new-post/ -src/content/blog/my-new-post/index.md -``` - -Posts should include front matter with relevant metadata. - -### Briefs (Short Notes) - -Organized into categories represented as folders within `src/content/briefs/`, and stored *directly* as markdown files (no additional nesting / generic `index.md`). -For example, the following contains two briefs—one in the `swift-warts` category and one in the `claude-code` category: - -``` -src/content/briefs/swift-warts/my-swift-brief.md -src/content/briefs/claude-code/my-claude-brief.md -``` - -Categories are auto-discovered from folder names. To add a new category, simply create a new folder. -Categories may also customize their display name, description, and sort priority by establishing a `category.yaml` file in the category folder; this is useful because the category name is used in multiple places throughout the site, and benefits from having distinct, contextually-appropriate representations. - -### Projects (Descriptions of Projects) - -Structured analogously to "Blog Posts`, but placed in `src/content/projects/`, instead. - -## Directory Structure - -- `src/`: Source code - - `components/`: Astro components - - `content/`: Content collections (blog, briefs, projects) - - `blog/`: where blog posts live - - `briefs/`: where briefs live - - `projects/`: where project pages live - - `layouts/`: Page layouts - - `pages/`: Routes and pages - - `styles/`: Global styles - - `lib/`: Utilities -- `public/`: Static assets (fonts, images, etc.) -- `dist/`: Build output (generated, not in repo) -- `.github/workflows/`: GitHub Actions workflows - -## Testing and QA - -The repository has Playwright browser automation available via MCP for testing and QA purposes. This enables: - -- Visual testing and screenshot capture -- Navigation testing -- Content verification -- Browser automation tasks +@AGENTS.md