solmate-skills 1.0.0

package/AGENTS.md

@@ -0,0 +1,90 @@
+# Antigravity Global Standards & Communication Rules
+
+## 1. 커뮤니케이션 및 승인 원칙
+- **이모지 금지**: 사용자와의 모든 대화에서 이모지(Emoji) 및 이모티콘 사용을 전면 금지한다. 전문적이고 명확한 텍스트로만 소통한다.
+- **선 답변 후 작업**: 질문이나 설명 요청 시, 파일 수정이나 명령 실행을 금지하고 상세한 텍스트 답변을 최우선으로 제공한다.
+- **수정 승인 필수**: 코드를 수정하기 전에 반드시 수정 계획을 보고하고 명시적 승인을 얻어야 한다.
+- **명확한 목적 제시**: 코드 수정을 시작할 때는 반드시 "OOO 기능을 수정하겠습니다"라고 목적을 명확히 밝힌다.
+- **근거 기반 답변**: "아마도 그럴 것이다" 식의 추측을 금지하고, 반드시 도구(Tool)로 현재 상태를 검증한 후 답변한다.
+- **충분한 논의 및 완료 지연 금지 (Anti-Rush)**: AI가 임의로 단계의 완료를 정의하지 않는다. 사용자가 "이제 코딩을 시작하자"고 먼저 말하거나 "더 이상 보완할 점이 없다"고 확언할 때까지는 현재 단계에 머물며 더 깊은 질문과 논의를 지속한다. "다음으로 넘어갈까요?"라는 재촉 대신 "현재 단계에서 더 구체화하거나 보완할 점이 있을까요?"라고 묻는다.
+- **Self-Reflection Check (자가 점검 강제)**: 코드를 수정하는 도구를 호출하기 전에, 반드시 다음 질문에 스스로 답해야 한다.
+  - "이 수정에 대한 내용을 사용자에게 설명했는가? (Y/N)"
+  - "이 수정에 대한 사용자의 명시적 승인이 있는가? (Y/N)"
+  - "이 수정이 기존 시스템에 영향을 주지 않는다는 근거가 있는가? (Y/N)"
+  - **"코드 시작전 사용자에게 충분한 질문과 의견교환을 하였는가?(Y/N)" (필수)**
+
+
+## 2. 문서 관리 표준 (5-Layer Structure)
+개발 문서는 다음 **폴더명과 역할**을 갖는 5단계 구조를 엄격히 준수한다.
+
+| 순번 | 폴더명 | 역할 |
+| :--- | :--- | :--- |
+| 1 | `docs/01_Concept_Design/` | 컨셉과 디자인 가이드. 기획, 비전, 개요, UI 디자인, 기능 설명. |
+| 2 | `docs/02_UI_Screens/` | UI 스크린. 페이지별 완성된 모습·프로토타입 리뷰·화면 흐름 확인. |
+| 3 | `docs/03_Technical_Specs/` | 기술 명세. 데이터·API 등 기술적 약속, DB 스키마·구현 가이드. |
+| 4 | `docs/04_Logic_Progress/` | 로직과 진행. 백로그(진행 상태) + 비즈니스 로직·상태 관리·알고리즘. |
+| 5 | `docs/05_QA_Validation/` | QA와 검증. 테스트 시나리오·QA 체크리스트·시스템 검증. |
+
+### 2.1. `docs/01_Concept_Design` — 컨셉·디자인
+- **역할**: 프로젝트의 기획, 목적, 개요, UI 디자인, 기능 설명을 담는 컨셉·디자인 가이드.
+- **포함 예**: `VISION.md`, `OVERVIEW.md`, `UI_DESIGN.md`, `ROADMAP.md`
+
+### 2.2. `docs/02_UI_Screens` — UI 스크린
+- **역할**: UI-First 전략에 따른 프로토타입 결과물(스크린샷, 흐름도) 및 리뷰. 페이지별 완성 모습 확인.
+- **포함 예**: `PROTOTYPE_REVIEW.md`, `SCREEN_FLOW.md`, 페이지별 리뷰 문서
+
+### 2.3. `docs/03_Technical_Specs` — 기술 명세
+- **역할**: 개발자가 참고하는 구체적 지시서. 데이터·API 등 기술적 약속.
+- **포함 예**: `DB_SCHEMA.md`, `API_SPECS.md`, `STORAGE_POLICY.md`, 구현 가이드
+
+### 2.4. `docs/04_Logic_Progress` — 로직·진행
+- **역할**: 백로그(진행 상태)와 비즈니스 로직·상태 관리·알고리즘 결합. UI와 데이터(DB/API) 연결 설계.
+- **포함 예**: `00_BACKLOG.md`, `00_ARCHIVE/`, 상태 머신·알고리즘 설계 문서
+
+### 2.5. `docs/05_QA_Validation` — QA·검증
+- **역할**: 구현 기능의 검증. 단순 테스트를 넘어 시스템 검증.
+- **포함 예**: `test_scenarios.md`, `qa_checklist.md`, 리뷰·감사 문서
+
+### 2.6. 문서 작성 표준 (Metadata & Naming)
+- **날짜 기록 필수**: 모든 문서의 최상단에는 **작성 일시(Created Date)**와 **최종 수정 일시(Last Updated Date)**를 반드시 명시한다.
+- **날짜 형식**: `YYYY-MM-DD HH:mm` 포맷을 사용한다.
+- **파일 네이밍**: 모든 파일명 앞에는 `01_`과 같은 **순번(Numbering)**을 반드시 붙여 생성 순서와 계층을 명확히 한다. (예: `01_VISION.md`, `02_UI_DESIGN.md`)
+- **Interactive Process**: 문서를 작성할 때 AI가 독단적으로 내용을 채우지 않는다. 초안 작성 전, **반드시 사용자에게 핵심 질문을 던지고 답변을 바탕으로 문서를 작성(Ask before Write)**한다.
+
+## 3. 개발 표준 및 품질
+- **UI 중심 개발 전략 (UI-First)**: Concept_Design -> UI_Screens -> Technical_Specs -> Logic_Progress 순서를 따른다.
+- **git commit 필수**: 중요 작업 전 반드시 git commit을 수행한다.
+- **커밋 메시지 형식**: `type(scope): subject` 포맷을 따른다.
+  - **Type**: `feat`(기능), `fix`(버그), `docs`(문서), `style`(포맷), `refactor`(리팩토링), `test`(테스트), `chore`(기타)
+  - **Subject**: 한글로 명확하게 요약한다. (예: `feat(login): 소셜 로그인 API 연동`)
+
+### 3.1. 프로젝트 구조 표준 (Monorepo Strategy)
+- **Root Directory (`/`)**: 프로젝트의 **관리(Management)** 영역이다. Git, 문서(docs), 설정(AGENTS.md), 루트 package.json(스크립트 위임용)을 포함한다. 실제 앱 소스는 App Directory에 둔다.
+- **App Directory (`/web`)**: 실제 **구현(Implementation)** 영역이다. **본 프로젝트(Mastering-Bitcoin-RAG)는 `web/`을 App Directory로 사용한다.** 소스 코드(`src/`), 빌드 설정, 의존성(package.json, node_modules)을 `web/`에서 관리한다.
+- **Git 관리**: 반드시 **Root Directory**에서 수행하여 문서와 코드를 통합 관리한다.
+- **배포 설정**: 배포 서비스의 Root Directory를 **App Directory(`web/`)** 로 지정하거나, Build Command를 `cd web && npm run build` 등으로 설정한다.
+
+## 4. Skills & AI Capabilities
+AI 에이전트는 본 프로젝트에 설치된 다음 **14개 스킬**을 활용하여 작업을 수행하며, 모든 작업 결과물은 이 스킬들의 검증 가이드를 통과해야 한다.
+
+| 카테고리 | 스킬명 | 주요 역할 |
+| :--- | :--- | :--- |
+| **운영 및 거버넌스** | `manage-collaboration` | 팀장/팀원 가이드 기반 협업 표준(브랜치, PR, 승인 등) 강제 |
+| | `manage-docs` | 5단계 문서 구조 및 메타데이터 표준 관리 |
+| | `manage-skills` | 검증 스킬의 누락 탐지 및 최신화 (Self-Maint.) |
+| **품질 검증 (QA)** | `verify-implementation` | 모든 `verify-*` 스킬의 통합 순차 실행 및 보고 (Template) |
+| | `verify-docs` | 문서 레이어 정합성 및 네이밍/메타데이터 검증 (Template) |
+| | `verify-drizzle-schema` | Drizzle 스키마 설계 정합성 및 기술 표준 검증 (Template) |
+| **개발 및 설계** | `dev-conventions` | 코딩 표준 및 프로젝트 컨벤션 준수 여부 확인 |
+| | `design-md` | 디자인 명세 및 기획 문서 작성 최적화 |
+| | `react-components` | UI 컴포넌트 설계 및 구현 표준 가이드 |
+| | `shadcn-ui` | shadcn/ui 라이브러리 활용 및 커스텀 가이드 |
+| **특수 도구** | `stitch-loop` | UI 디자인-코드 간의 반복 작업 고도화 |
+| | `remotion` | 비디오 프로그래밍을 통한 시각화 자료 생성 |
+| | `obsidian-sync` | 지식 베이스(Obsidian)와의 동기화 및 관리 |
+| | `enhance-prompt` | AI 프롬프트 최적화 및 페르소나 강화 |
+
+---
+
+## 5. 최종 약속
+AI 에이전트는 본 **AGENTS.md**를 모든 판단의 최우선 근거로 삼는다. 문서에 정의되지 않은 작업을 수행할 경우 반드시 사용자에게 구현 전 문서 업데이트 필요성을 먼저 확인한다.

package/README.md

@@ -0,0 +1,42 @@
+# solmate-skills
+
+Curated skills for Solmate projects. Easily share and install AI tool skills across your team.
+
+## Installation
+
+You don't need to install this package globally. Simply use `npx`:
+
+```bash
+# List available skills
+npx solmate-skills list
+
+# Install all available skills
+npx solmate-skills install all
+
+# Install a specific skill (e.g., manage-docs)
+npx solmate-skills install manage-docs
+```
+
+## How it works
+
+When you run the `install` command, the script will:
+1. Check for the selected skill in this package.
+2. Copy the skill folder to `.agent/skills/<skill-name>` in your current project.
+
+## Available Skills
+
+- `design-md`: Design and UI patterns.
+- `dev-conventions`: Development standards and rules.
+- `enhance-prompt`: Advanced prompting techniques.
+- `implementation-workflow`: Step-by-step implementation guides.
+- `manage-collaboration`: Team collaboration protocols.
+- `manage-docs`: Documentation structure and standards.
+- `manage-skills`: Skill management and creation tool.
+- `obsidian-sync`: Obsidian integration.
+- `react-components`: Curated React components.
+- `remotion`: Video creation as code.
+- `shadcn-ui`: Custom Shadcn UI components.
+- `stitch-loop`: Integration with Stitch.
+- `verify-docs`: Documentation audit tool.
+- `verify-drizzle-schema`: Drizzle schema verification.
+- `verify-implementation`: Logic and flow verification.

package/bin/cli.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const IGNORED_FOLDERS = ['bin', 'node_modules', '.git', '.github', '.gemini', '.agent'];
+const IGNORED_FILES = ['package.json', 'package-lock.json', 'AGENTS.md', 'SKILL.md', 'init-skills.sh', 'README.md', '.DS_Store', 'old_AGENTS.md'];
+
+const packageRoot = path.join(__dirname, '..');
+const targetProjectRoot = process.cwd();
+const targetSkillsDir = path.join(targetProjectRoot, '.agent', 'skills');
+
+function getAvailableSkills() {
+    return fs.readdirSync(packageRoot, { withFileTypes: true })
+        .filter(dirent => dirent.isDirectory() && !IGNORED_FOLDERS.includes(dirent.name))
+        .map(dirent => dirent.name);
+}
+
+function copyFolderSync(from, to) {
+    if (!fs.existsSync(to)) {
+        fs.mkdirSync(to, { recursive: true });
+    }
+    fs.readdirSync(from).forEach(element => {
+        const fromPath = path.join(from, element);
+        const toPath = path.join(to, element);
+        if (fs.lstatSync(fromPath).isDirectory()) {
+            copyFolderSync(fromPath, toPath);
+        } else {
+            fs.copyFileSync(fromPath, toPath);
+        }
+    });
+}
+
+function listSkills() {
+    const skills = getAvailableSkills();
+    console.log('\nAvailable skills to install:');
+    skills.forEach(skill => console.log(` - ${skill}`));
+    console.log('\nUsage: npx solmate-skills install <skill-name> | install-all\n');
+}
+
+function installSkill(skillName) {
+    const skills = getAvailableSkills();
+
+    if (skillName === 'install-all') {
+        console.log('Installing all skills...');
+        skills.forEach(s => installSkill(s));
+        return;
+    }
+
+    if (!skills.includes(skillName)) {
+        console.error(`Error: Skill "${skillName}" not found.`);
+        process.exit(1);
+    }
+
+    const sourcePath = path.join(packageRoot, skillName);
+    const destPath = path.join(targetSkillsDir, skillName);
+
+    console.log(`Installing ${skillName}...`);
+    copyFolderSync(sourcePath, destPath);
+    console.log(`Successfully installed ${skillName} to .agent/skills/${skillName}`);
+}
+
+const args = process.argv.slice(2);
+const command = args[0];
+const subCommand = args[1];
+
+if (!command || command === 'list') {
+    listSkills();
+} else if (command === 'install') {
+    if (!subCommand) {
+        console.error('Error: Please specify a skill name or "all".');
+        listSkills();
+        process.exit(1);
+    }
+    if (subCommand === 'all' || subCommand === 'install-all') {
+        installSkill('install-all');
+    } else {
+        installSkill(subCommand);
+    }
+} else if (command === 'install-all' || command === 'all') {
+    installSkill('install-all');
+} else {
+    console.log(`Unknown command: ${command}`);
+    listSkills();
+}

package/design-md/README.md

@@ -0,0 +1,34 @@
+# Stitch Design System Documentation Skill
+
+## Install
+
+```bash
+npx add-skill google-labs-code/stitch-skills --skill design-md --global
+```
+
+## Example Prompt
+
+```text
+Analyze my Furniture Collection project's Home screen and generate a comprehensive DESIGN.md file documenting the design system.
+```
+
+## Skill Structure
+
+This repository follows the **Agent Skills** open standard. Each skill is self-contained with its own logic, workflow, and reference materials.
+
+```text
+design-md/
+├── SKILL.md           — Core instructions & workflow
+├── examples/          — Sample DESIGN.md outputs
+└── README.md          — This file
+```
+
+## How it Works
+
+When activated, the agent follows a structured design analysis pipeline:
+
+1. **Retrieval**: Uses the Stitch MCP Server to fetch project screens, HTML code, and design metadata.
+2. **Extraction**: Identifies design tokens including colors, typography, spacing, and component patterns.
+3. **Translation**: Converts technical CSS/Tailwind values into descriptive, natural design language.
+4. **Synthesis**: Generates a comprehensive DESIGN.md following the semantic design system format.
+5. **Alignment**: Ensures output follows Stitch Effective Prompting Guide principles for optimal screen generation.

package/design-md/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: design-md
+description: Analyze Stitch projects and synthesize a semantic design system into DESIGN.md files
+allowed-tools:
+  - "stitch*:*"
+  - "Read"
+  - "Write"
+  - "web_fetch"
+---
+
+# Stitch DESIGN.md Skill
+
+You are an expert Design Systems Lead. Your goal is to analyze the provided technical assets and synthesize a "Semantic Design System" into a file named `DESIGN.md`.
+
+## Overview
+
+This skill helps you create `DESIGN.md` files that serve as the "source of truth" for prompting Stitch to generate new screens that align perfectly with existing design language. Stitch interprets design through "Visual Descriptions" supported by specific color values.
+
+## Prerequisites
+
+- Access to the Stitch MCP Server
+- A Stitch project with at least one designed screen
+- Access to the Stitch Effective Prompting Guide: https://stitch.withgoogle.com/docs/learn/prompting/
+
+## The Goal
+
+The `DESIGN.md` file will serve as the "source of truth" for prompting Stitch to generate new screens that align perfectly with the existing design language. Stitch interprets design through "Visual Descriptions" supported by specific color values.
+
+## Retrieval and Networking
+
+To analyze a Stitch project, you must retrieve screen metadata and design assets using the Stitch MCP Server tools:
+
+1. **Namespace discovery**: Run `list_tools` to find the Stitch MCP prefix. Use this prefix (e.g., `mcp_stitch:`) for all subsequent calls.
+
+2. **Project lookup** (if Project ID is not provided):
+   - Call `[prefix]:list_projects` with `filter: "view=owned"` to retrieve all user projects
+   - Identify the target project by title or URL pattern
+   - Extract the Project ID from the `name` field (e.g., `projects/13534454087919359824`)
+
+3. **Screen lookup** (if Screen ID is not provided):
+   - Call `[prefix]:list_screens` with the `projectId` (just the numeric ID, not the full path)
+   - Review screen titles to identify the target screen (e.g., "Home", "Landing Page")
+   - Extract the Screen ID from the screen's `name` field
+
+4. **Metadata fetch**: 
+   - Call `[prefix]:get_screen` with both `projectId` and `screenId` (both as numeric IDs only)
+   - This returns the complete screen object including:
+     - `screenshot.downloadUrl` - Visual reference of the design
+     - `htmlCode.downloadUrl` - Full HTML/CSS source code
+     - `width`, `height`, `deviceType` - Screen dimensions and target platform
+     - Project metadata including `designTheme` with color and style information
+
+5. **Asset download**:
+   - Use `web_fetch` or `read_url_content` to download the HTML code from `htmlCode.downloadUrl`
+   - Optionally download the screenshot from `screenshot.downloadUrl` for visual reference
+   - Parse the HTML to extract Tailwind classes, custom CSS, and component patterns
+
+6. **Project metadata extraction**:
+   - Call `[prefix]:get_project` with the project `name` (full path: `projects/{id}`) to get:
+     - `designTheme` object with color mode, fonts, roundness, custom colors
+     - Project-level design guidelines and descriptions
+     - Device type preferences and layout principles
+
+## Analysis & Synthesis Instructions
+
+### 1. Extract Project Identity (JSON)
+- Locate the Project Title
+- Locate the specific Project ID (e.g., from the `name` field in the JSON)
+
+### 2. Define the Atmosphere (Image/HTML)
+Evaluate the screenshot and HTML structure to capture the overall "vibe." Use evocative adjectives to describe the mood (e.g., "Airy," "Dense," "Minimalist," "Utilitarian").
+
+### 3. Map the Color Palette (Tailwind Config/JSON)
+Identify the key colors in the system. For each color, provide:
+- A descriptive, natural language name that conveys its character (e.g., "Deep Muted Teal-Navy")
+- The specific hex code in parentheses for precision (e.g., "#294056")
+- Its specific functional role (e.g., "Used for primary actions")
+
+### 4. Translate Geometry & Shape (CSS/Tailwind)
+Convert technical `border-radius` and layout values into physical descriptions:
+- Describe `rounded-full` as "Pill-shaped"
+- Describe `rounded-lg` as "Subtly rounded corners"
+- Describe `rounded-none` as "Sharp, squared-off edges"
+
+### 5. Describe Depth & Elevation
+Explain how the UI handles layers. Describe the presence and quality of shadows (e.g., "Flat," "Whisper-soft diffused shadows," or "Heavy, high-contrast drop shadows").
+
+## Output Guidelines
+
+- **Language:** Use descriptive design terminology and natural language exclusively
+- **Format:** Generate a clean Markdown file following the structure below
+- **Precision:** Include exact hex codes for colors while using descriptive names
+- **Context:** Explain the "why" behind design decisions, not just the "what"
+
+## Output Format (DESIGN.md Structure)
+
+```markdown
+# Design System: [Project Title]
+**Project ID:** [Insert Project ID Here]
+
+## 1. Visual Theme & Atmosphere
+(Description of the mood, density, and aesthetic philosophy.)
+
+## 2. Color Palette & Roles
+(List colors by Descriptive Name + Hex Code + Functional Role.)
+
+## 3. Typography Rules
+(Description of font family, weight usage for headers vs. body, and letter-spacing character.)
+
+## 4. Component Stylings
+* **Buttons:** (Shape description, color assignment, behavior).
+* **Cards/Containers:** (Corner roundness description, background color, shadow depth).
+* **Inputs/Forms:** (Stroke style, background).
+
+## 5. Layout Principles
+(Description of whitespace strategy, margins, and grid alignment.)
+```
+
+## Usage Example
+
+To use this skill for the Furniture Collection project:
+
+1. **Retrieve project information:**
+   ```
+   Use the Stitch MCP Server to get the Furniture Collection project
+   ```
+
+2. **Get the Home page screen details:**
+   ```
+   Retrieve the Home page screen's code, image, and screen object information
+   ```
+
+3. **Reference best practices:**
+   ```
+   Review the Stitch Effective Prompting Guide at:
+   https://stitch.withgoogle.com/docs/learn/prompting/
+   ```
+
+4. **Analyze and synthesize:**
+   - Extract all relevant design tokens from the screen
+   - Translate technical values into descriptive language
+   - Organize information according to the DESIGN.md structure
+
+5. **Generate the file:**
+   - Create `DESIGN.md` in the project directory
+   - Follow the prescribed format exactly
+   - Ensure all color codes are accurate
+   - Use evocative, designer-friendly language
+
+## Best Practices
+
+- **Be Descriptive:** Avoid generic terms like "blue" or "rounded." Use "Ocean-deep Cerulean (#0077B6)" or "Gently curved edges"
+- **Be Functional:** Always explain what each design element is used for
+- **Be Consistent:** Use the same terminology throughout the document
+- **Be Visual:** Help readers visualize the design through your descriptions
+- **Be Precise:** Include exact values (hex codes, pixel values) in parentheses after natural language descriptions
+
+## Tips for Success
+
+1. **Start with the big picture:** Understand the overall aesthetic before diving into details
+2. **Look for patterns:** Identify consistent spacing, sizing, and styling patterns
+3. **Think semantically:** Name colors by their purpose, not just their appearance
+4. **Consider hierarchy:** Document how visual weight and importance are communicated
+5. **Reference the guide:** Use language and patterns from the Stitch Effective Prompting Guide
+
+## Common Pitfalls to Avoid
+
+- ❌ Using technical jargon without translation (e.g., "rounded-xl" instead of "generously rounded corners")
+- ❌ Omitting color codes or using only descriptive names
+- ❌ Forgetting to explain functional roles of design elements
+- ❌ Being too vague in atmosphere descriptions
+- ❌ Ignoring subtle design details like shadows or spacing patterns

package/design-md/examples/DESIGN.md

@@ -0,0 +1,154 @@
+# Design System: Furniture Collections List
+**Project ID:** 13534454087919359824
+
+## 1. Visual Theme & Atmosphere
+
+The Furniture Collections List embodies a **sophisticated, minimalist sanctuary** that marries the pristine simplicity of Scandinavian design with the refined visual language of luxury editorial presentation. The interface feels **spacious and tranquil**, prioritizing breathing room and visual clarity above all else. The design philosophy is gallery-like and photography-first, allowing each furniture piece to command attention as an individual art object.
+
+The overall mood is **airy yet grounded**, creating an aspirational aesthetic that remains approachable and welcoming. The interface feels **utilitarian in its restraint** but elegant in its execution, with every element serving a clear purpose while maintaining visual sophistication. The atmosphere evokes the serene ambiance of a high-end furniture showroom where customers can browse thoughtfully without visual overwhelm.
+
+**Key Characteristics:**
+- Expansive whitespace creating generous breathing room between elements
+- Clean, architectural grid system with structured content blocks
+- Photography-first presentation with minimal UI interference
+- Whisper-soft visual hierarchy that guides without shouting
+- Refined, understated interactive elements
+- Professional yet inviting editorial tone
+
+## 2. Color Palette & Roles
+
+### Primary Foundation
+- **Warm Barely-There Cream** (#FCFAFA) – Primary background color. Creates an almost imperceptible warmth that feels more inviting than pure white, serving as the serene canvas for the entire experience.
+- **Crisp Very Light Gray** (#F5F5F5) – Secondary surface color used for card backgrounds and content areas. Provides subtle visual separation while maintaining the airy, ethereal quality.
+
+### Accent & Interactive
+- **Deep Muted Teal-Navy** (#294056) – The sole vibrant accent in the palette. Used exclusively for primary call-to-action buttons (e.g., "Shop Now", "View all products"), active navigation links, selected filter states, and subtle interaction highlights. This sophisticated anchor color creates visual focus points without disrupting the serene neutral foundation.
+
+### Typography & Text Hierarchy
+- **Charcoal Near-Black** (#2C2C2C) – Primary text color for headlines and product names. Provides strong readable contrast while being softer and more refined than pure black.
+- **Soft Warm Gray** (#6B6B6B) – Secondary text used for body copy, product descriptions, and supporting metadata. Creates clear typographic hierarchy without harsh contrast.
+- **Ultra-Soft Silver Gray** (#E0E0E0) – Tertiary color for borders, dividers, and subtle structural elements. Creates separation so gentle it's almost imperceptible.
+
+### Functional States (Reserved for system feedback)
+- **Success Moss** (#10B981) – Stock availability, confirmation states, positive indicators
+- **Alert Terracotta** (#EF4444) – Low stock warnings, error states, critical alerts
+- **Informational Slate** (#64748B) – Neutral system messages, informational callouts
+
+## 3. Typography Rules
+
+**Primary Font Family:** Manrope  
+**Character:** Modern, geometric sans-serif with gentle humanist warmth. Slightly rounded letterforms that feel contemporary yet approachable.
+
+### Hierarchy & Weights
+- **Display Headlines (H1):** Semi-bold weight (600), generous letter-spacing (0.02em for elegance), 2.75-3.5rem size. Used sparingly for hero sections and major page titles.
+- **Section Headers (H2):** Semi-bold weight (600), subtle letter-spacing (0.01em), 2-2.5rem size. Establishes clear content zones and featured collections.
+- **Subsection Headers (H3):** Medium weight (500), normal letter-spacing, 1.5-1.75rem size. Product names and category labels.
+- **Body Text:** Regular weight (400), relaxed line-height (1.7), 1rem size. Descriptions and supporting content prioritize comfortable readability.
+- **Small Text/Meta:** Regular weight (400), slightly tighter line-height (1.5), 0.875rem size. Prices, availability, and metadata remain legible but visually recessive.
+- **CTA Buttons:** Medium weight (500), subtle letter-spacing (0.01em), 1rem size. Balanced presence without visual aggression.
+
+### Spacing Principles
+- Headers use slightly expanded letter-spacing for refined elegance
+- Body text maintains generous line-height (1.7) for effortless reading
+- Consistent vertical rhythm with 2-3rem between related text blocks
+- Large margins (4-6rem) between major sections to reinforce spaciousness
+
+## 4. Component Stylings
+
+### Buttons
+- **Shape:** Subtly rounded corners (8px/0.5rem radius) – approachable and modern without appearing playful or childish
+- **Primary CTA:** Deep Muted Teal-Navy (#294056) background with pure white text, comfortable padding (0.875rem vertical, 2rem horizontal)
+- **Hover State:** Subtle darkening to deeper navy, smooth 250ms ease-in-out transition
+- **Focus State:** Soft outer glow in the primary color for keyboard navigation accessibility
+- **Secondary CTA (if needed):** Outlined style with Deep Muted Teal-Navy border, transparent background, hover fills with whisper-soft teal tint
+
+### Cards & Product Containers
+- **Corner Style:** Gently rounded corners (12px/0.75rem radius) creating soft, refined edges
+- **Background:** Alternates between Warm Barely-There Cream and Crisp Very Light Gray based on layering needs
+- **Shadow Strategy:** Flat by default. On hover, whisper-soft diffused shadow appears (`0 2px 8px rgba(0,0,0,0.06)`) creating subtle depth
+- **Border:** Optional hairline border (1px) in Ultra-Soft Silver Gray for delicate definition when shadows aren't present
+- **Internal Padding:** Generous 2-2.5rem creating comfortable breathing room for content
+- **Image Treatment:** Full-bleed at the top of cards, square or 4:3 ratio, seamless edge-to-edge presentation
+
+### Navigation
+- **Style:** Clean horizontal layout with generous spacing (2-3rem) between menu items
+- **Typography:** Medium weight (500), subtle uppercase, expanded letter-spacing (0.06em) for refined sophistication
+- **Default State:** Charcoal Near-Black text
+- **Active/Hover State:** Smooth 200ms color transition to Deep Muted Teal-Navy
+- **Active Indicator:** Thin underline (2px) in Deep Muted Teal-Navy appearing below current section
+- **Mobile:** Converts to elegant hamburger menu with sliding drawer
+
+### Inputs & Forms
+- **Stroke Style:** Refined 1px border in Soft Warm Gray
+- **Background:** Warm Barely-There Cream with transition to Crisp Very Light Gray on focus
+- **Corner Style:** Matching button roundness (8px/0.5rem) for visual consistency
+- **Focus State:** Border color shifts to Deep Muted Teal-Navy with subtle outer glow
+- **Padding:** Comfortable 0.875rem vertical, 1.25rem horizontal for touch-friendly targets
+- **Placeholder Text:** Ultra-Soft Silver Gray, elegant and unobtrusive
+
+### Product Cards (Specific Pattern)
+- **Image Area:** Square (1:1) or landscape (4:3) ratio filling card width completely
+- **Content Stack:** Product name (H3), brief descriptor, material/finish, price
+- **Price Display:** Emphasized with semi-bold weight (600) in Charcoal Near-Black
+- **Hover Behavior:** Gentle lift effect (translateY -4px) combined with enhanced shadow
+- **Spacing:** Consistent 1.5rem internal padding below image
+
+## 5. Layout Principles
+
+### Grid & Structure
+- **Max Content Width:** 1440px for optimal readability and visual balance on large displays
+- **Grid System:** Responsive 12-column grid with fluid gutters (24px mobile, 32px desktop)
+- **Product Grid:** 4 columns on large desktop, 3 on desktop, 2 on tablet, 1 on mobile
+- **Breakpoints:** 
+  - Mobile: <768px
+  - Tablet: 768-1024px  
+  - Desktop: 1024-1440px
+  - Large Desktop: >1440px
+
+### Whitespace Strategy (Critical to the Design)
+- **Base Unit:** 8px for micro-spacing, 16px for component spacing
+- **Vertical Rhythm:** Consistent 2rem (32px) base unit between related elements
+- **Section Margins:** Generous 5-8rem (80-128px) between major sections creating dramatic breathing room
+- **Edge Padding:** 1.5rem (24px) mobile, 3rem (48px) tablet/desktop for comfortable framing
+- **Hero Sections:** Extra-generous top/bottom padding (8-12rem) for impactful presentation
+
+### Alignment & Visual Balance
+- **Text Alignment:** Left-aligned for body and navigation (optimal readability), centered for hero headlines and featured content
+- **Image to Text Ratio:** Heavily weighted toward imagery (70-30 split) reinforcing photography-first philosophy
+- **Asymmetric Balance:** Large hero images offset by compact, refined text blocks
+- **Visual Weight Distribution:** Strategic use of whitespace to draw eyes to hero products and primary CTAs
+- **Reading Flow:** Clear top-to-bottom, left-to-right pattern with intentional focal points
+
+### Responsive Behavior & Touch
+- **Mobile-First Foundation:** Core experience designed and perfected for smallest screens first
+- **Progressive Enhancement:** Additional columns, imagery, and details added gracefully at larger breakpoints
+- **Touch Targets:** Minimum 44x44px for all interactive elements (WCAG AAA compliant)
+- **Image Optimization:** Responsive images with appropriate resolutions for each breakpoint, lazy-loading for performance
+- **Collapsing Strategy:** Navigation collapses to hamburger, grid reduces columns, padding scales proportionally
+
+## 6. Design System Notes for Stitch Generation
+
+When creating new screens for this project using Stitch, reference these specific instructions:
+
+### Language to Use
+- **Atmosphere:** "Sophisticated minimalist sanctuary with gallery-like spaciousness"
+- **Button Shapes:** "Subtly rounded corners" (not "rounded-md" or "8px")
+- **Shadows:** "Whisper-soft diffused shadows on hover" (not "shadow-sm")
+- **Spacing:** "Generous breathing room" and "expansive whitespace"
+
+### Color References
+Always use the descriptive names with hex codes:
+- Primary CTA: "Deep Muted Teal-Navy (#294056)"
+- Backgrounds: "Warm Barely-There Cream (#FCFAFA)" or "Crisp Very Light Gray (#F5F5F5)"
+- Text: "Charcoal Near-Black (#2C2C2C)" or "Soft Warm Gray (#6B6B6B)"
+
+### Component Prompts
+- "Create a product card with gently rounded corners, full-bleed square product image, and whisper-soft shadow on hover"
+- "Design a primary call-to-action button in Deep Muted Teal-Navy (#294056) with subtle rounded corners and comfortable padding"
+- "Add a navigation bar with generous spacing between items, using medium-weight Manrope with subtle uppercase and expanded letter-spacing"
+
+### Incremental Iteration
+When refining existing screens:
+1. Focus on ONE component at a time (e.g., "Update the product grid cards")
+2. Be specific about what to change (e.g., "Increase the internal padding of product cards from 1.5rem to 2rem")
+3. Reference this design system language consistently