Website & UI Component Library
Relevant source files
The following files were used as context for generating this wiki page:The Caro website (caro.sh) is the marketing and documentation hub for the AI-powered CLI tool. It is designed to be professional, interactive, and trustworthy, reflecting the brand's personality: friendly, helpful, and safety-focused. The site is built using Astro and features a comprehensive blog and interactive elements.
To ensure a consistent and high-quality user experience, a Storybook-based UI component library is being implemented. This library will contain reusable React components, forming a cohesive design system that governs the site's visual identity. The development prioritizes mobile-first design, accessibility (WCAG AA), and dark mode support.
Sources: website/NEXT_SESSION_PROMPT.md, presentation/roadmap-slides.md:37-43, presentation/DELIVERABLES_SUMMARY.md:55-61
Website Strategy & Roadmap
The website is a key deliverable for the project's v1.2.0 launch, scheduled for March 31, 2026. The strategy focuses on creating a professional public presence, building a community, and providing comprehensive documentation.
Sources: presentation/roadmap-slides.md:37-43
The following diagram illustrates the project timeline, with the website launch as a central part of the v1.2.0 milestone.
Sources: presentation/roadmap-slides.md:19-25
Key Deliverables
The website launch encompasses several key areas:
| Category | Deliverables |
|---|---|
| Website | Interactive terminal landing page, ASCII art morphs, SEO optimization, Florentine design. |
| Documentation | Astro Starlight site, comprehensive manual, LLM architecture docs. |
| Strategy | 12-month roadmap, launch plan, UGC content pipeline. |
| Community | Mission & values statement, contributor attribution page, i18n support (Simplified Chinese). |
| Content | Interactive MediaPipe elements, AI shell pitch deck. |
| DevOps | Automated releases, CI/CD pipeline for the website. |
Sources: presentation/roadmap-slides.md:46-77
One of the core features of the website is an interactive terminal on the landing page. This will likely involve a multi-turn conversational flow to guide users, similar to the ambiguity clarification flow designed for the CLI tool itself.
Sources: presentation/roadmap-slides.md:49, specs/006-intelligent-prompt-generation/spec.md:275-303
The diagram below shows a potential sequence for this interactive terminal experience.
UI Component Library
To maintain design consistency and development velocity, a dedicated UI component library is being built using Storybook and React. This library will be integrated into the Astro-based website.
Sources: website/NEXT_SESSION_PROMPT.md:11-12
Architecture and Setup
The component library follows a standard structure, with each component in its own directory containing the component file, CSS module, and Storybook story.
Sources: website/NEXT_SESSION_PROMPT.md:76-92
Setup Steps:
- Initialize Storybook with React support.
- Install addons for accessibility (
@storybook/addon-a11y) and viewport testing (@storybook/addon-viewport). - Configure a custom theme and mobile viewports (320px, 375px, 768px).
- Integrate with the Astro site using
@astrojs/react.
Sources: website/NEXT_SESSION_PROMPT.md:17-25, 36-38
Design System & Theming
The visual identity is guided by specific brand principles and a set of design tokens.
Brand Guidelines:
- Personality: Friendly, helpful, safety-focused.
- Visual Style: Modern, clean, playful but professional.
- Animations: Subtle (0.2s ease), respecting
prefers-reduced-motion. - Typography:
Inter/systemfor UI,Monaco/Menlofor code.
Sources: website/NEXT_SESSION_PROMPT.md:58-64
Design Tokens:
The core theme is defined by CSS variables located in src/layouts/Layout.astro.
| Token | Light Mode | Dark Mode | Purpose |
|---|---|---|---|
--color-primary | #ff8c42 | #ff8c42 | Main brand color, links |
--color-primary-dark | #ff6b35 | #ff6b35 | Darker shade for gradients |
--color-support | #ea4aaa | #ea4aaa | Accent color (e.g., support button) |
--color-bg | #ffffff | #1a1a1a | Main background |
--color-bg-secondary | #f5f5f5 | #2d2d2d | Secondary background |
Sources: website/NEXT_SESSION_PROMPT.md:41-51, website/BLOG_STRUCTURE_GUIDE.md:12-13
A key UX requirement is that all interactive elements must have a minimum touch target of 44x44px to be touch-friendly.
Sources: website/NEXT_SESSION_PROMPT.md:53, 70
Core Components
The initial implementation focuses on three core, reusable components.
Button
The Button component is the primary interactive element, with multiple variants and sizes.
| Prop | Type | Options | Description |
|---|---|---|---|
variant | string | primary, secondary, ghost, support | Controls the button's visual style. |
size | string | sm, md, lg | Controls the button's padding and font size. |
fullWidth | boolean | true, false | Makes the button span the full width of its container. |
primary: Orange gradient.secondary: Outline style.support: Pink accent color.
Sources: website/NEXT_SESSION_PROMPT.md:28-33
Toggle
A custom switch component for settings like dark mode.
- Desktop Size: 50px × 28px track.
- Mobile Size: 44px × 24px track.
- Animation: 0.2s thumb slide.
- Branded Variant: Uses the primary orange color when active.
Sources: website/NEXT_SESSION_PROMPT.md:34-39
Badge
Used for displaying status or tags.
- Variants:
primary,success(green),warning,info. - Shape: Pill-shaped with a 12px border-radius.
- Font Size: Small (11-12px).
Sources: website/NEXT_SESSION_PROMPT.md:40-45
Blog Architecture
The website's blog is a central feature for communication and documentation. Its structure and style are meticulously planned to ensure consistency, engagement, and SEO performance.
Sources: website/BLOG_STRUCTURE_GUIDE.md
Ideal Post Structure
Each blog post follows a defined content architecture to maximize reader engagement and clarity.
Engagement Elements
To improve readability and maintain user interest, the blog uses a variety of visual elements. A key recommendation is to break up long sections of text every 2-3 paragraphs with an element like a code block, list, image, or a highlight box.
Sources: website/BLOG_STRUCTURE_GUIDE.md:73-80
Highlight Boxes (Callouts)
The blog enhances the standard .highlight class with several variants to convey different types of information, each with a distinct color and icon.
| Class | Icon | Border Color | Purpose |
|---|---|---|---|
.highlight-info | ℹ️ | #3b82f6 (Blue) | Additional context or helpful notes. |
.highlight-warning | ⚠️ | #f59e0b (Yellow) | Cautions or important considerations. |
.highlight-success | ✅ | #10b981 (Green) | Recommended approaches or best practices. |
.highlight-tip | 💡 | #8b5cf6 (Purple) | Pro-tips or expert insights. |
Sources: website/BLOG_STRUCTURE_GUIDE.md:175-202, 205-228
The CSS for these variants uses a left border and a subtle background gradient.
.highlight {
display: flex;
gap: 16px;
background: linear-gradient(135deg, var(--color-bg-tertiary) 0%, var(--color-bg) 100%);
border-left: 4px solid #ff8c42;
padding: 20px 24px;
margin: 30px 0;
border-radius: 8px;
}
.highlight-warning {
border-left-color: #f59e0b;
background: linear-gradient(135deg, rgba(245, 158, 11, 0.1) 0%, var(--color-bg) 100%);
}
Sources: website/BLOG_STRUCTURE_GUIDE.md:206-218, 219-222
SEO and Discoverability
The blog architecture includes robust support for SEO and social sharing through enhanced meta tags and structured data. The BlogPost.astro layout is designed to generate a full suite of Open Graph, Twitter, and JSON-LD metadata based on the post's frontmatter.
Sources: website/BLOG_STRUCTURE_GUIDE.md:301-349
Conclusion
The Caro website and its underlying UI component library are critical to the project's public launch and long-term success. The website serves as the primary channel for marketing, documentation, and community engagement. The development of a formal design system using Storybook and React ensures that the site is not only visually appealing and on-brand but also maintainable, scalable, and accessible. The detailed planning for both the component library and the blog architecture demonstrates a commitment to quality and a professional user experience.
Sources: presentation/roadmap-slides.md:37-43, website/NEXT_SESSION_PROMPT.md:11-12, [website/BLOG_STRUCTURE_GUIDE.md:3-9]