Phase 2 - Design System & Tokens

Overview

• Track: Both (MVP & Showcase)
• Duration: 1-2 days
• Dependencies: Phase 0-1 completed
• Deliverables: Design tokens, Tailwind config, CSS architecture, accessibility primitives

Entry Criteria

• Content architecture defined
• TypeScript configured
• Tailwind CSS installed
• Design requirements gathered

Implementation Steps

Step	Task	MVP	Showcase	Notes
2.01	Define color palette	✅	✅	HSL for flexibility
2.02	Set up typography scale	✅	✅	Fluid type optional
2.03	Create spacing system	✅	✅	Consistent scale
2.04	Define radius tokens	✅	✅	Border radius system
2.05	Add shadow system	✅	✅	Elevation tokens
2.06	Create motion tokens	✅	✅	Transitions/animations (ensure surfaced in tailwind.config.ts for utility classes like transition-base, duration-fast, etc.)
2.07	Set up dark mode	✅	✅	CSS variables approach
2.08	Add a11y primitives	✅	✅	Focus, contrast
2.09	Configure Tailwind	✅	✅	Extend with tokens
2.10	Create token build	✅	✅	JSON to CSS/Tailwind
2.11	Document usage	✅	✅	Guidelines for devs
2.12	Add WCAG checks	✅	✅	Script to iterate all semantic text/background pairs for WCAG AA

Tailwind CSS Considerations

Tailwind CSS is now stable and provides significant improvements over v3, including better performance, enhanced design token integration, and improved developer experience.

Key v3.4.4 Benefits:

• Better Performance: Faster build times and smaller CSS output
• Enhanced Design Tokens: Native CSS variables support
• Improved DX: Better IDE support and error messages
• Migration Path: Clear upgrade path from v3 configurations

Current Implementation: The project uses tailwindcss: "^3.4.4" which ensures you get the latest stable v4 patches while maintaining compatibility.

Image Optimization and Future Scalability

Current Approach: The project currently leverages Astro’s built-in <Image> component for image optimization. This component, often paired with the Sharp.js library under the hood (as per default Astro configurations), handles tasks like resizing, format conversion (e.g., to AVIF, WebP), and generating responsive srcset attributes. This is generally sufficient for optimal performance and image handling at the current scale.

Future Consideration: Image CDN Fallback/Enhancement While the built-in solution is robust, if the project experiences a significant spike in traffic, or if the requirements for delivering numerous device-specific image variants become more complex, integrating a dedicated image CDN should be considered.

Services like Cloudflare Images (or similar offerings like Cloudinary, Imgix) provide benefits such as:

• Real-time Resizing and Optimization: Images can be transformed on-the-fly based on request parameters or device characteristics, reducing the need to pre-generate all variants.
• Global CDN Delivery: Faster image delivery worldwide.
• Advanced Features: Watermarking, format negotiation, and more sophisticated art direction capabilities.

This is not an immediate requirement but a potential future enhancement to keep in mind for scalability and advanced image manipulation needs. The decision to integrate such a service would involve cost considerations and a re-evaluation of the image delivery pipeline.

Common Pitfalls

1. Hardcoded Colors: Using hex values directly in components

   • Solution: Always use token classes or CSS variables

2. Missing Dark Mode: Not considering dark mode from start

   • Solution: Use semantic tokens that work in both modes

3. Poor Contrast: Not validating WCAG compliance

   • Solution: Run contrast checks on all color combinations

4. Motion Sickness: Not respecting prefers-reduced-motion

   • Solution: Add motion guards in global CSS

Exit Criteria

• Color palette defined with semantic naming
• Typography scale configured
• Spacing system consistent
• Border radius tokens defined
• Shadow system created
• Motion tokens established
• Dark mode functioning
• Accessibility utilities created
• Tailwind extended with tokens
• Token build script working
• WCAG contrast validated
• Usage guidelines documented

Rollback Strategy

If design system needs major changes:

1. Token Updates:

   # Keep old tokens
   cp tokens/base.json tokens/base.json.backup
   # Test new tokens
   pnpm run build:tokens # Note: You'll need to create the './scripts/build-tokens.js' file as part of this phase.
   # Validate contrast
   pnpm run validate:contrast

2. Tailwind Config Issues:

   • Revert tailwind.config.ts
   • Clear Tailwind cache
   • Rebuild CSS

3. Breaking Changes:

   • Use CSS variables for gradual migration
   • Keep old classes temporarily
   • Document deprecations

AI Assistant Notes

Key Files to Reference

• tokens/base.json - Core design tokens
• tailwind.config.ts - Tailwind configuration
• src/styles/global.css - Global styles
• Token build script

Common Prompts for This Phase

• “Create accessible color palette with WCAG AA compliance”
• “Set up Tailwind with design tokens”
• “Implement dark mode with CSS variables”
• “Create fluid typography scale”

Context Requirements

• Brand colors if any
• Typography preferences
• Motion preferences
• Accessibility requirements