UI Implementation & Component Guide

This document is the authoritative source of truth for UI implementation in this project.

When acting as an AI assistant or automated refactoring agent:

1. Strict Adherence: Strictly follow all rules, constraints, and architectural principles defined here.
2. Aesthetic Priority: Maintain a clean and minimalistic style in all UI generations.
3. Token Priority: Prioritize design token usage, DaisyUI conventions, and structural integrity.
4. No Silent Overrides: Break rules only if explicitly and intentionally instructed. If instructed to override:
   • State the overridden rule.
   • Explain the architectural impact.
   • Confirm intent, then proceed.

• Whitespace: Use generous padding/margins. Avoid cluttered layouts.
• Visual Weight: Favor thin borders and subtle shadows over heavy gradients/patterns.
• Typography: Use weight and token colors (Content vs. Content-Secondary) for hierarchy, not just size.
• Interaction: Animations must be subtle, smooth, and fast (150ms-200ms transitions).

Enforce the use of tokens for adjusting design across viewports.

• Large Breakpoint: Use--breakpoint-lg(CSS equivalent:@media (min-width: 1024px)orlg:modifier in Tailwind).
• Max Site Width: Use--breakpoint-2xl(CSS equivalent:@media (min-width: 1536px)or2xl:modifier).
• Centering: As a secondary measure for bounding maximum width on specific components, enforcemx-auto(e.g.,max-w-screen-2xl mx-auto).

• NEVER hardcode Hex colors or Tailwind gray scales.
• ALWAYS use CSS variables (--color-*) or DaisyUI semantic classes (bg-base-200,text-base-content).
• Every component must automatically adapt todarkandlightthemes via these tokens.

Directly apply CSS utility classes to HTML tags as the primary styling method. Do not abstract into custom CSS unless strictly necessary.

Tailwind/DaisyUI Class Ordering Convention: To maintain readability and token efficiency, order classes logically:

1. DaisyUI Base: (btn,card,menu)
2. DaisyUI Modifiers: (btn-primary,card-body)
3. Layout & Display: (block,flex,grid,absolute)
4. Spacing & Sizing: (w-full,max-w-md,p-4,m-2)
5. Typography: (text-lg,font-bold,text-center)
6. Colors & Backgrounds: (bg-base-100,text-base-content)
7. Borders & Effects: (border,border-theme,shadow-sm)
8. Responsive & States: (hover:bg-base-200,lg:p-8,focus-visible:ring)

Class logic extracted for clarity and strict ordering. Order: Base -> Modifiers -> Layout -> Spacing -> Typography -> Colors -> Borders -> States.

To ensure accessibility and visual harmony, always pair background semantic colors with their corresponding content tokens. Never use a base content color on a primary background.

As example:

Requirement: If a component usesbg-primary, any text or icons within it must usetext-primary-contentto guarantee correct contrast ratios.

First, enforce the use of standard CSS classes. If complex design requires explicitly overriding DaisyUI structure, custom rules must be created under the following constraints:

Global CSS helpers must complement the framework, not compete with it.

• Keep rules single-responsibility.
• Scope them to theme token alignment.
• Avoid shorthand properties that override multiple CSS behaviors at once.
• Always pair custom helpers with Tailwind directional utilities, never override them.

If a component requires structural layout changes:

• Implement them in a component-scoped class (e.g., inside an Astro<style>block).
• Document why the change is required.
• Guiding Question: Does this align the component with the theme system—or does it override how DaisyUI intended the component to behave? If it alters intended behavior, it must be scoped locally and carefully reviewed.

• .force-theme-tokens: Use strictly for debugging/migration.
• .debug-highlight: Use during audits to visually detect elements utilizing legacy or hardcoded styles.

• Theme Definitions:src/styles/global.css
• Tailwind Config:tailwind.config.cjs

• Clutter: Crowding elements without sufficient whitespace padding.
• Hardcoded Values: Hex colors or non-theme structural values.
• Structural Overrides in Global Helpers: Adding global CSS classes that change DaisyUI’s core layout behavior.
• Inaccessibility: Missingaria-labelsor poor contrast ratios (e.g., usingtext-base-contentonbg-primary).
• Poor Responsive Design: Missing breakpoint rules or failing to cap widths with--breakpoint-2xlandmx-auto.

• Is the design clean, minimalistic, and utilizing adequate whitespace?
• Are HTML tags styled directly using the correct class ordering convention?
• Are colors correctly paired for contrast (e.g.,primary+primary-content)?
• Does the visual check pass seamlessly in both Light and Dark themes?
• Are structural overrides strictly component-scoped and not leaking globally?
• Is the design fully responsive, respectinglgand2xlmax-width breakpoints?
• Are interactive elements keyboard accessible (:focus-visible)?

The design system must be theme-driven, consistent, and predictable. If a new design requirement conflicts with these rules, update the theme tokens—not the individual components.

Would you like me to create a reusable Astro component snippet that implements the primary/primary-content pairing and the max-width layout tokens?