Frontend Design Principles
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The web-projects repository follows a modern, component-driven frontend architecture designed for high performance, content accessibility, and rich user experiences. The project leverages a monorepo structure to share UI libraries and configurations across multiple applications, ranging from personal blogs to complex data extraction tools.
The core philosophy centers on using specialized tools for specific tasks: Astro for high-performance content delivery, React for interactive components, and TailwindCSS for utility-first styling. Accessibility, particularly regarding color contrast and WCAG compliance, is treated as a first-class citizen within the ecosystem.
Sources: CLAUDE.md, AGENTS.md, apps/dotori-note/README.md
Core Tech Stack and Architecture
The repository utilizes a workspace-based architecture managed by Turborepo and Bun. This allows for a clear separation between user-facing applications and reusable logic/UI packages.
Component and Library Distribution
UI components are primarily developed within the packages/ui-craft and @siluat/shadcn-ui workspaces. This enables consistent design patterns across different playgrounds and production apps.
The diagram shows how internal packages are distributed across applications and testing environments.
Sources: CLAUDE.md:19-35, packages/ui-craft/README.md
Technology Selection Criteria
| Technology | Role | Reason for Choice |
|---|---|---|
| Astro | Web Framework | High performance; supports "Islands Architecture" to reuse React components while keeping static content fast. |
| React 19 | UI Library | Standard for interactive UI; facilitates component reuse across the monorepo. |
| TailwindCSS 4.0 | Styling | Utility-first approach; integrated with shadcn/ui for rapid development and consistent themes. |
| Framer Motion | Animation | Powering the ui-craft library for smooth, declarative UI animations. |
Sources: CLAUDE.md:38-46, apps/dotori-note/README.md:27-46
Accessibility and Design Tokens
A key principle in the project is strict adherence to Web Content Accessibility Guidelines (WCAG), specifically regarding color contrast.
Contrast Validation Logic
The project includes a dedicated package @siluat/color-contrast that provides utility functions for real-time accessibility checks. This logic is integrated directly into the documentation and UI components.
This flow illustrates how the system evaluates colors and suggests accessible alternatives using OKLCH color space adjustments.
Sources: apps/color-contrast-docs/components/color-checker.tsx:188-218
Compliance Standards
- Normal Text: 4.5:1 (AA), 7:1 (AAA)
- Large Text (18pt+): 3:1 (AA), 4.5:1 (AAA)
Sources: apps/color-contrast-docs/components/color-checker.tsx:244-250
Content Design and Navigation
For content-heavy applications like dotori-note, the project emphasizes "Autolink Headings" to improve navigation and linkability.
Heading Structure and Logic
The system automatically generates unique IDs for headings using rehype-slug and wraps them in anchor tags via rehype-autolink-headings.
// apps/dotori-note/astro.config.ts:11-26
const rehypeAutolinkHeadingsOptions: RehypeAutolinkHeadingsOptions = {
behavior: 'wrap',
properties: {
className: [
'autolink-heading',
'no-underline',
'hover:underline',
'hover:underline-offset-4',
'hover:before:inline-block',
'hover:before:content-["#"]',
'hover:before:w-[0.7em]',
'hover:before:ml-[-0.7em]',
],
ariaLabel: 'Link to this heading',
tabindex: 0,
},
};
Sources: apps/dotori-note/astro.config.ts:11-26
Animation and Visual Polish
Visual feedback is provided through the @siluat/ui-craft package. The design process follows a specific lifecycle:
- Crafting: Components are developed in
packages/ui-craft. - Visual Testing: Components are refined in
playgrounds/ui-craft-playgroundto fine-tune animation parameters before deployment. - Deployment: Refined components are exported via
./react/*patterns for use in production apps.
Sources: packages/ui-craft/README.md, CLAUDE.md:65-68
Summary
The frontend design principles of this project prioritize performance through Astro's static generation, maintainability via a structured monorepo, and inclusivity through automated WCAG contrast validation. By separating logic into discrete packages (contrast calculation, UI animations, shared configs), the project ensures that high-quality design patterns are consistently applied across all web properties.