From d8faa74283cb8f4e3d1f6748aefd52b80695fa1e Mon Sep 17 00:00:00 2001 From: Farrel Augusta Dinata Date: Sun, 11 Oct 2026 18:20:07 +0700 Subject: [PATCH 1/3] doc: add CLAUDE.md files referencing AGENTS.md in multiple directories --- blockchain/CLAUDE.md | 1 + client/CLAUDE.md | 1 + ml/CLAUDE.md | 1 + server/CLAUDE.md | 1 + 4 files changed, 4 insertions(+) create mode 100644 blockchain/CLAUDE.md create mode 100644 client/CLAUDE.md create mode 100644 ml/CLAUDE.md create mode 100644 server/CLAUDE.md diff --git a/blockchain/CLAUDE.md b/blockchain/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/blockchain/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/client/CLAUDE.md b/client/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/client/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/ml/CLAUDE.md b/ml/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/ml/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/server/CLAUDE.md b/server/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/server/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md From 139487beef40f1c4b3ff668c421e0a1efcbddc37 Mon Sep 17 00:00:00 2001 From: Farrel Augusta Dinata Date: Sun, 11 Oct 2026 18:37:59 +0700 Subject: [PATCH 2/3] doc: enhance ai agent guide for ui related --- .agents/skills/design-md/README.md | 34 + .agents/skills/design-md/SKILL.md | 188 + .agents/skills/design-md/examples/DESIGN.md | 177 + .../react-component-architecture/SKILL.md | 14 +- .agents/skills/shadcn/SKILL.md | 295 + .agents/skills/shadcn/agents/openai.yml | 5 + .agents/skills/shadcn/assets/shadcn-small.png | Bin 0 -> 1049 bytes .agents/skills/shadcn/assets/shadcn.png | Bin 0 -> 3852 bytes .../shadcn/assets/showcase/color-pair.tsx | 126 + .../shadcn/assets/showcase/preview-states.css | 14 + .../shadcn/assets/showcase/state-matrix.tsx | 72 + .agents/skills/shadcn/cli.md | 290 + .agents/skills/shadcn/customization.md | 210 + .agents/skills/shadcn/design-system-page.md | 268 + .agents/skills/shadcn/design-system.md | 386 + .agents/skills/shadcn/evals/evals.json | 126 + .agents/skills/shadcn/mcp.md | 105 + .agents/skills/shadcn/registry.md | 277 + .agents/skills/shadcn/rules/base-vs-radix.md | 308 + .agents/skills/shadcn/rules/chat.md | 248 + .agents/skills/shadcn/rules/composition.md | 215 + .agents/skills/shadcn/rules/forms.md | 194 + .agents/skills/shadcn/rules/icons.md | 101 + .agents/skills/shadcn/rules/styling.md | 184 + .../shadcn/scripts/showcase-coverage.mjs | 53 + .agents/skills/ui-ux-pro-max/SKILL.md | 220 + .../ui-ux-pro-max/data/app-interface.csv | 33 + .../ui-ux-pro-max/data/catalog-summary.json | 78 + .agents/skills/ui-ux-pro-max/data/charts.csv | 26 + .agents/skills/ui-ux-pro-max/data/colors.csv | 193 + .../ui-ux-pro-max/data/data-provenance.json | 1226 + .../data/google-font-licenses.json | 15730 ++++++++++++ .../ui-ux-pro-max/data/google-fonts.csv | 1935 ++ .agents/skills/ui-ux-pro-max/data/icons.csv | 106 + .agents/skills/ui-ux-pro-max/data/landing.csv | 35 + .agents/skills/ui-ux-pro-max/data/motion.csv | 18 + .../data/phosphor-icons-upstream.json | 21224 ++++++++++++++++ .../skills/ui-ux-pro-max/data/products.csv | 193 + .../ui-ux-pro-max/data/react-performance.csv | 45 + .../ui-ux-pro-max/data/stacks/angular.csv | 51 + .../ui-ux-pro-max/data/stacks/astro.csv | 54 + .../ui-ux-pro-max/data/stacks/avalonia.csv | 57 + .../ui-ux-pro-max/data/stacks/flutter.csv | 53 + .../data/stacks/html-tailwind.csv | 60 + .../ui-ux-pro-max/data/stacks/javafx.csv | 76 + .../data/stacks/jetpack-compose.csv | 53 + .../ui-ux-pro-max/data/stacks/laravel.csv | 51 + .../ui-ux-pro-max/data/stacks/nextjs.csv | 62 + .../ui-ux-pro-max/data/stacks/nuxt-ui.csv | 77 + .../ui-ux-pro-max/data/stacks/nuxtjs.csv | 68 + .../data/stacks/react-native.csv | 52 + .../ui-ux-pro-max/data/stacks/react.csv | 67 + .../ui-ux-pro-max/data/stacks/shadcn.csv | 69 + .../ui-ux-pro-max/data/stacks/svelte.csv | 56 + .../ui-ux-pro-max/data/stacks/swiftui.csv | 51 + .../ui-ux-pro-max/data/stacks/threejs.csv | 54 + .../skills/ui-ux-pro-max/data/stacks/uno.csv | 60 + .../skills/ui-ux-pro-max/data/stacks/uwp.csv | 56 + .../skills/ui-ux-pro-max/data/stacks/vue.csv | 50 + .../ui-ux-pro-max/data/stacks/winui.csv | 60 + .../skills/ui-ux-pro-max/data/stacks/wpf.csv | 57 + .agents/skills/ui-ux-pro-max/data/styles.csv | 89 + .../skills/ui-ux-pro-max/data/typography.csv | 75 + .../ui-ux-pro-max/data/ui-reasoning.csv | 193 + .../ui-ux-pro-max/data/ux-guidelines.csv | 120 + .../ui-ux-pro-max/references/pro-rules.md | 123 + .../references/quick-reference.md | 256 + .agents/skills/ui-ux-pro-max/scripts/core.py | 993 + .../ui-ux-pro-max/scripts/design_system.py | 1668 ++ .../scripts/reasoning_contract.py | 123 + .../skills/ui-ux-pro-max/scripts/search.py | 177 + .../tests/fixtures/catalogs/google-api.json | 34 + .../fixtures/catalogs/google-catalog.json | 64 + .../fixtures/catalogs/google-existing.csv | 3 + .../fixtures/catalogs/google-metadata.json | 17 + .../fixtures/catalogs/google-overrides.json | 7 + .../tests/fixtures/catalogs/icons-curated.csv | 4 + .../fixtures/catalogs/phosphor-core.json | 23 + .../fixtures/catalogs/phosphor-package.json | 13 + .../catalogs/phosphor-react-exports.json | 4 + .../catalogs/phosphor-react-package.json | 5 + .../tests/fixtures/relevance-baseline.json | 3024 +++ .../tests/fixtures/relevance-cases.json | 1506 ++ .../tests/fixtures/relevance-thresholds.json | 114 + .../scripts/tests/test_catalog_refresh.py | 354 + .../test_catalog_summary_line_endings.py | 78 + .../ui-ux-pro-max/scripts/tests/test_core.py | 343 + .../scripts/tests/test_core_data_quality.py | 198 + .../scripts/tests/test_data_contracts.py | 421 + .../scripts/tests/test_design_system_mode.py | 233 + .../scripts/tests/test_design_system_stack.py | 61 + .../test_native_desktop_stack_freshness.py | 179 + .../scripts/tests/test_relevance_evaluator.py | 182 + .../scripts/tests/test_skill_script_paths.py | 82 + .../scripts/tests/test_style_taxonomy.py | 175 + .../tests/test_text_layout_resilience.py | 120 + .../scripts/tests/test_web_stack_freshness.py | 177 + .../ui-ux-pro-max/scripts/validate_data.py | 1095 + .gitignore | 5 + client/AGENTS.md | 91 +- .../AGENTS/rekakarbon-frontend-agent-spec.md | 2619 -- client/DESIGN.md | 272 +- skills-lock.json | 18 + 103 files changed, 58828 insertions(+), 2756 deletions(-) create mode 100644 .agents/skills/design-md/README.md create mode 100644 .agents/skills/design-md/SKILL.md create mode 100644 .agents/skills/design-md/examples/DESIGN.md create mode 100644 .agents/skills/shadcn/SKILL.md create mode 100644 .agents/skills/shadcn/agents/openai.yml create mode 100644 .agents/skills/shadcn/assets/shadcn-small.png create mode 100644 .agents/skills/shadcn/assets/shadcn.png create mode 100644 .agents/skills/shadcn/assets/showcase/color-pair.tsx create mode 100644 .agents/skills/shadcn/assets/showcase/preview-states.css create mode 100644 .agents/skills/shadcn/assets/showcase/state-matrix.tsx create mode 100644 .agents/skills/shadcn/cli.md create mode 100644 .agents/skills/shadcn/customization.md create mode 100644 .agents/skills/shadcn/design-system-page.md create mode 100644 .agents/skills/shadcn/design-system.md create mode 100644 .agents/skills/shadcn/evals/evals.json create mode 100644 .agents/skills/shadcn/mcp.md create mode 100644 .agents/skills/shadcn/registry.md create mode 100644 .agents/skills/shadcn/rules/base-vs-radix.md create mode 100644 .agents/skills/shadcn/rules/chat.md create mode 100644 .agents/skills/shadcn/rules/composition.md create mode 100644 .agents/skills/shadcn/rules/forms.md create mode 100644 .agents/skills/shadcn/rules/icons.md create mode 100644 .agents/skills/shadcn/rules/styling.md create mode 100644 .agents/skills/shadcn/scripts/showcase-coverage.mjs create mode 100644 .agents/skills/ui-ux-pro-max/SKILL.md create mode 100644 .agents/skills/ui-ux-pro-max/data/app-interface.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/catalog-summary.json create mode 100644 .agents/skills/ui-ux-pro-max/data/charts.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/colors.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/data-provenance.json create mode 100644 .agents/skills/ui-ux-pro-max/data/google-font-licenses.json create mode 100644 .agents/skills/ui-ux-pro-max/data/google-fonts.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/icons.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/landing.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/motion.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/phosphor-icons-upstream.json create mode 100644 .agents/skills/ui-ux-pro-max/data/products.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/react-performance.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/angular.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/astro.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/avalonia.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/flutter.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/html-tailwind.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/javafx.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/jetpack-compose.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/laravel.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/nextjs.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/nuxt-ui.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/nuxtjs.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/react-native.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/react.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/shadcn.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/svelte.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/swiftui.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/threejs.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/uno.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/uwp.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/vue.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/winui.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/stacks/wpf.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/styles.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/typography.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/ui-reasoning.csv create mode 100644 .agents/skills/ui-ux-pro-max/data/ux-guidelines.csv create mode 100644 .agents/skills/ui-ux-pro-max/references/pro-rules.md create mode 100644 .agents/skills/ui-ux-pro-max/references/quick-reference.md create mode 100644 .agents/skills/ui-ux-pro-max/scripts/core.py create mode 100644 .agents/skills/ui-ux-pro-max/scripts/design_system.py create mode 100644 .agents/skills/ui-ux-pro-max/scripts/reasoning_contract.py create mode 100644 .agents/skills/ui-ux-pro-max/scripts/search.py create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/fixtures/catalogs/google-api.json create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/fixtures/catalogs/google-catalog.json create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/fixtures/catalogs/google-existing.csv create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/fixtures/catalogs/google-metadata.json create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/fixtures/catalogs/google-overrides.json create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/fixtures/catalogs/icons-curated.csv create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/fixtures/catalogs/phosphor-core.json create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/fixtures/catalogs/phosphor-package.json create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/fixtures/catalogs/phosphor-react-exports.json create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/fixtures/catalogs/phosphor-react-package.json create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/fixtures/relevance-baseline.json create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/fixtures/relevance-cases.json create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/fixtures/relevance-thresholds.json create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/test_catalog_refresh.py create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/test_catalog_summary_line_endings.py create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/test_core.py create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/test_core_data_quality.py create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/test_data_contracts.py create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/test_design_system_mode.py create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/test_design_system_stack.py create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/test_native_desktop_stack_freshness.py create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/test_relevance_evaluator.py create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/test_skill_script_paths.py create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/test_style_taxonomy.py create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/test_text_layout_resilience.py create mode 100644 .agents/skills/ui-ux-pro-max/scripts/tests/test_web_stack_freshness.py create mode 100644 .agents/skills/ui-ux-pro-max/scripts/validate_data.py delete mode 100644 client/AGENTS/rekakarbon-frontend-agent-spec.md diff --git a/.agents/skills/design-md/README.md b/.agents/skills/design-md/README.md new file mode 100644 index 0000000..8f52207 --- /dev/null +++ b/.agents/skills/design-md/README.md @@ -0,0 +1,34 @@ +# Stitch Design System Documentation Skill + +## Install + +```bash +npx skills add 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. diff --git a/.agents/skills/design-md/SKILL.md b/.agents/skills/design-md/SKILL.md new file mode 100644 index 0000000..29ddd4f --- /dev/null +++ b/.agents/skills/design-md/SKILL.md @@ -0,0 +1,188 @@ +--- +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 diff --git a/.agents/skills/design-md/examples/DESIGN.md b/.agents/skills/design-md/examples/DESIGN.md new file mode 100644 index 0000000..71533f9 --- /dev/null +++ b/.agents/skills/design-md/examples/DESIGN.md @@ -0,0 +1,177 @@ +# 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 diff --git a/.agents/skills/react-component-architecture/SKILL.md b/.agents/skills/react-component-architecture/SKILL.md index 18982a7..541933b 100644 --- a/.agents/skills/react-component-architecture/SKILL.md +++ b/.agents/skills/react-component-architecture/SKILL.md @@ -17,25 +17,25 @@ Use this skill when creating new components, refactoring existing ones, building ### 1.1 Architecture Flow ``` -View layer (client/src/components/, client/src/portal/) +View layer (client/src/components/, client/src/routes/) ↓ consumes state & actions -Zustand Global Store (client/src/store/useCarbonStore.js) +Zustand Global Store (client/src/store/useCarbonStore.ts) ↓ calls asynchronously Repository Layer (client/src/repositories/.repository.ts) ↓ branches via VITE_USE_MOCK_DATA Mock Data (client/src/lib/mock/.ts) OR API Client (client/src/lib/api.ts) ``` -> **CRITICAL RULE (`test:arch`):** View components (`components/`, `portal/`) MUST NOT import directly from `client/src/lib/mock/`. All data access must pass through Zustand Store → Repository interfaces. +> **CRITICAL RULE (`test:arch`):** View components (`components/`, `routes/`) MUST NOT import directly from `client/src/lib/mock/`. All data access must pass through Zustand Store → Repository interfaces. --- ## 2 — UI & Layout Conventions -### 2.1 Right Navigation Drawer Rule +### 2.1 Navigation Architecture Rules -- RekaKarbon main portal **MUST NOT** use a permanent left sidebar. -- Navigation must be implemented via the right sliding drawer component ([`RightDrawer.jsx`](../../../client/src/components/RightDrawer.jsx)) triggered by top-right control buttons. +- **Authenticated Portals (`/kth`, `/emitter`, `/regulator`, `/auditor`)**: Managed by [`PortalLayout.tsx`](../../../client/src/components/layout/PortalLayout.tsx) with a responsive, role-isolated [`PortalSidebar.tsx`](../../../client/src/components/layout/PortalSidebar.tsx). +- **Public Map View (`/_index`)**: Uses the full-screen canvas layout with the sliding right drawer component ([`RightDrawer.tsx`](../../../client/src/components/RightDrawer.tsx)) triggered by top-right control buttons. ### 2.2 Color Tokens & Primary Gradient @@ -58,7 +58,7 @@ Mock Data (client/src/lib/mock/.ts) OR API Client (client/src/lib/api.t ## 3 — Map & Geodetic Spatial Data -- All map and spatial area calculations in RekaKarbon modules MUST utilize standardized geodetic helper functions in [`geodetics.js`](../../../client/src/utils/geodetics.js). +- All map and spatial area calculations in RekaKarbon modules MUST utilize standardized geodetic helper functions in [`geodetics.ts`](../../../client/src/utils/geodetics.ts). - Direct, unstandardized Euclidean/flat formulas for geographic spatial area computations are forbidden to prevent numerical data drift. --- diff --git a/.agents/skills/shadcn/SKILL.md b/.agents/skills/shadcn/SKILL.md new file mode 100644 index 0000000..3633fc9 --- /dev/null +++ b/.agents/skills/shadcn/SKILL.md @@ -0,0 +1,295 @@ +--- +name: shadcn +description: Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI, including chat interfaces. Provides project context, component docs, and usage examples. Applies when working with shadcn/ui, component registries, presets, --preset codes, or any project with a components.json file. Also triggers for "shadcn init", "create an app with --preset", "switch to --preset", and for building a design system or applying a DESIGN.md or brand spec to shadcn/ui. +user-invocable: false +allowed-tools: Bash(npx shadcn@latest *), Bash(pnpm dlx shadcn@latest *), Bash(bunx --bun shadcn@latest *) +--- + +# shadcn/ui + +A framework for building ui, components and design systems. Components are added as source code to the user's project via the CLI. + +> **IMPORTANT:** Run all CLI commands using the project's package runner: `npx shadcn@latest`, `pnpm dlx shadcn@latest`, or `bunx --bun shadcn@latest` — based on the project's `packageManager`. Examples below use `npx shadcn@latest` but substitute the correct runner for the project. + +## Current Project Context + +```json +!`npx shadcn@latest info --json` +``` + +The JSON above contains the project config and installed components. Use `npx shadcn@latest docs ` to get documentation and example URLs for any component. + +## Principles + +1. **Use existing components first.** Use `npx shadcn@latest search` to check registries before writing custom UI. Check community registries too. +2. **Compose, don't reinvent.** Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table. +3. **Use built-in variants before custom styles.** `variant="outline"`, `size="sm"`, etc. +4. **Use semantic colors.** `bg-primary`, `text-muted-foreground` — never raw values like `bg-blue-500`. + +## Critical Rules + +These rules are **always enforced**. Each links to a file with Incorrect/Correct code pairs. + +### Styling & Tailwind → [styling.md](./rules/styling.md) + +- **`className` for layout, not styling.** Never override component colors or typography. +- **No `space-x-*` or `space-y-*`.** Use `flex` with `gap-*`. For vertical stacks, `flex flex-col gap-*`. +- **Use `size-*` when width and height are equal.** `size-10` not `w-10 h-10`. +- **Use `truncate` shorthand.** Not `overflow-hidden text-ellipsis whitespace-nowrap`. +- **No manual `dark:` color overrides.** Use semantic tokens (`bg-background`, `text-muted-foreground`). +- **Use `cn()` for conditional classes.** Don't write manual template literal ternaries. +- **No manual `z-index` on overlay components.** Dialog, Sheet, Popover, etc. handle their own stacking. + +### Forms & Inputs → [forms.md](./rules/forms.md) + +- **Forms use `FieldGroup` + `Field`.** Never use raw `div` with `space-y-*` or `grid gap-*` for form layout. +- **`InputGroup` uses `InputGroupInput`/`InputGroupTextarea`.** Never raw `Input`/`Textarea` inside `InputGroup`. +- **Buttons inside inputs use `InputGroup` + `InputGroupAddon`.** +- **Option sets (2–7 choices) use `ToggleGroup`.** Don't loop `Button` with manual active state. +- **`FieldSet` + `FieldLegend` for grouping related checkboxes/radios.** Don't use a `div` with a heading. +- **Field validation uses `data-invalid` + `aria-invalid`.** `data-invalid` on `Field`, `aria-invalid` on the control. For disabled: `data-disabled` on `Field`, `disabled` on the control. + +### Component Structure → [composition.md](./rules/composition.md) + +- **Items always inside their Group.** `SelectItem` → `SelectGroup`. `DropdownMenuItem` → `DropdownMenuGroup`. `CommandItem` → `CommandGroup`. +- **Use `asChild` (radix) or `render` (base) for custom triggers.** Check `base` field from `npx shadcn@latest info`. → [base-vs-radix.md](./rules/base-vs-radix.md) +- **Dialog, Sheet, and Drawer always need a Title.** `DialogTitle`, `SheetTitle`, `DrawerTitle` required for accessibility. Use `className="sr-only"` if visually hidden. +- **Use full Card composition.** `CardHeader`/`CardTitle`/`CardDescription`/`CardContent`/`CardFooter`. Don't dump everything in `CardContent`. +- **Button has no `isPending`/`isLoading`.** Compose with `Spinner` + `data-icon` + `disabled`. +- **`TabsTrigger` must be inside `TabsList`.** Never render triggers directly in `Tabs`. +- **`Avatar` always needs `AvatarFallback`.** For when the image fails to load. + +### Use Components, Not Custom Markup → [composition.md](./rules/composition.md) + +- **Use existing components before custom markup.** Check if a component exists before writing a styled `div`. +- **Callouts use `Alert`.** Don't build custom styled divs. +- **Empty states use `Empty`.** Don't build custom empty state markup. +- **Toast follows the project base.** Use `toast` from the `toast` component for + Base UI projects. Use `toast()` from `sonner` for Radix and React Aria + projects. +- **Use `Separator`** instead of `
` or `
`. +- **Use `Skeleton`** for loading placeholders. No custom `animate-pulse` divs. +- **Use `Badge`** instead of custom styled spans. + +### Icons → [icons.md](./rules/icons.md) + +- **Icons in `Button` use `data-icon`.** `data-icon="inline-start"` or `data-icon="inline-end"` on the icon. +- **No sizing classes on icons inside components.** Components handle icon sizing via CSS. No `size-4` or `w-4 h-4`. +- **Pass icons as objects, not string keys.** `icon={CheckIcon}`, not a string lookup. + +### Chat & Messaging → [chat.md](./rules/chat.md) + +- **Chat UI composes the chat primitives.** Conversations use `MessageScroller`, rows use `Message`, surfaces use `Bubble`. Never hand-rolled bubble `div`s or a raw scroll container. +- **`MessageScroller` owns scroll behavior.** Streaming follow, anchoring, and jump-to-latest (`MessageScrollerButton`) are built in. Don't write a `useStickToBottom`/`ResizeObserver` hook. +- **Attachments use `Attachment`; system notes and dividers use `Marker`.** Not `Item` cards or `Separator` + a label. + +### CLI + +- **Never decode preset codes or build preset URLs manually.** Use `npx shadcn@latest preset decode `, `preset url `, or `preset open `. For project-aware preset detection, use `npx shadcn@latest preset resolve`. +- **Apply preset codes directly with the CLI.** Use `npx shadcn@latest apply ` for existing projects, or `npx shadcn@latest init --preset ` when initializing. + +## Key Patterns + +These are the most common patterns that differentiate correct shadcn/ui code. For edge cases, see the linked rule files above. + +```tsx +// Form layout: FieldGroup + Field, not div + Label. + + + Email + + + + +// Validation: data-invalid on Field, aria-invalid on the control. + + Email + + Invalid email. + + +// Icons in buttons: data-icon, no sizing classes. + + +// Spacing: gap-*, not space-y-*. +
// correct +
// wrong + +// Equal dimensions: size-*, not w-* h-*. + // correct + // wrong + +// Status colors: Badge variants or semantic tokens, not raw colors. ++20.1% // correct ++20.1% // wrong +``` + +## Component Selection + +| Need | Use | +| -------------------------- | --------------------------------------------------------------------------------------------------- | +| Button/action | `Button` with appropriate variant | +| Form inputs | `Input`, `Select`, `Combobox`, `Switch`, `Checkbox`, `RadioGroup`, `Textarea`, `InputOTP`, `Slider` | +| Toggle between 2–5 options | `ToggleGroup` + `ToggleGroupItem` | +| Data display | `Table`, `Card`, `Badge`, `Avatar` | +| Navigation | `Sidebar`, `NavigationMenu`, `Breadcrumb`, `Tabs`, `Pagination` | +| Overlays | `Dialog` (modal), `Sheet` (side panel), `Drawer` (bottom sheet), `AlertDialog` (confirmation) | +| Feedback | `toast` (Base UI), `sonner` (Radix/Aria), `Alert`, `Progress`, `Skeleton`, `Spinner` | +| Command palette | `Command` inside `Dialog` | +| Charts | `Chart` (wraps Recharts) | +| Layout | `Card`, `Separator`, `Resizable`, `ScrollArea`, `Accordion`, `Collapsible` | +| Empty states | `Empty` | +| Menus | `DropdownMenu`, `ContextMenu`, `Menubar` | +| Tooltips/info | `Tooltip`, `HoverCard`, `Popover` | +| Chat / conversation UI | `MessageScroller`, `Message`, `Bubble`, `Attachment`, `Marker` | + +## Key Fields + +The injected project context contains these key fields: + +- **`aliases`** → use the actual alias prefix for imports (e.g. `@/`, `~/`), never hardcode. +- **`isRSC`** → when `true`, components using `useState`, `useEffect`, event handlers, or browser APIs need `"use client"` at the top of the file. Always reference this field when advising on the directive. +- **`tailwindVersion`** → `"v4"` uses `@theme inline` blocks; `"v3"` uses `tailwind.config.js`. +- **`tailwindCssFile`** → the global CSS file where custom CSS variables are defined. Always edit this file, never create a new one. +- **`style`** → component visual treatment (e.g. `nova`, `vega`). +- **`base`** → primitive library (`radix` or `base`). Affects component APIs and available props. +- **`iconLibrary`** → determines icon imports. Use `lucide-react` for `lucide`, `@tabler/icons-react` for `tabler`, etc. Never assume `lucide-react`. +- **`resolvedPaths`** → exact file-system destinations for components, utils, hooks, etc. +- **`framework`** → routing and file conventions (e.g. Next.js App Router vs Vite SPA). +- **`packageManager`** → use this for any non-shadcn dependency installs (e.g. `pnpm add date-fns` vs `npm install date-fns`). +- **`preset`** → resolved preset code and values for the current project. Use `npx shadcn@latest preset resolve --json` when you only need preset information. + +See [cli.md — `info` command](./cli.md) for the full field reference. + +## Component Docs, Examples, and Usage + +Run `npx shadcn@latest docs ` to get the URLs for a component's documentation, examples, and API reference. Fetch these URLs to get the actual content. + +```bash +npx shadcn@latest docs button dialog select +``` + +**When creating, fixing, debugging, or using a component, always run `npx shadcn@latest docs` and fetch the URLs first.** This ensures you're working with the correct API and usage patterns rather than guessing. + +## Workflow + +1. **Get project context** — already injected above. Run `npx shadcn@latest info` again if you need to refresh. +2. **Check installed components first** — before running `add`, always check the `components` list from project context or list the `resolvedPaths.ui` directory. Don't import components that haven't been added, and don't re-add ones already installed. +3. **Find components** — `npx shadcn@latest search`. +4. **Get docs and examples** — run `npx shadcn@latest docs ` to get URLs, then fetch them. Use `npx shadcn@latest view` to browse registry items you haven't installed. To preview changes to installed components, use `npx shadcn@latest add --diff`. +5. **Install or update** — `npx shadcn@latest add`. When updating existing components, use `--dry-run` and `--diff` to preview changes first (see [Updating Components](#updating-components) below). +6. **Fix imports in third-party components** — After adding components from community registries (e.g. `@bundui`, `@magicui`), check the added non-UI files for hardcoded import paths like `@/components/ui/...`. These won't match the project's actual aliases. Use `npx shadcn@latest info` to get the correct `ui` alias (e.g. `@workspace/ui/components`) and rewrite the imports accordingly. The CLI rewrites imports for its own UI files, but third-party registry components may use default paths that don't match the project. +7. **Review added components** — After adding a component or block from any registry, **always read the added files and verify they are correct**. Check for missing sub-components (e.g. `SelectItem` without `SelectGroup`), missing imports, incorrect composition, or violations of the [Critical Rules](#critical-rules). Also replace any icon imports with the project's `iconLibrary` from the project context (e.g. if the registry item uses `lucide-react` but the project uses `hugeicons`, swap the imports and icon names accordingly). Fix all issues before moving on. +8. **Registry must be explicit** — When the user asks to add a block or component, **do not guess the registry**. If no registry is specified (e.g. user says "add a login block" without specifying `@shadcn`, `@tailark`, `owner/repo`, etc.), ask which registry to use. Never default to a registry on behalf of the user. +9. **Switching presets** — Ask the user first: **overwrite**, **partial**, **merge**, or **skip**? + - **Inspect current preset**: `npx shadcn@latest preset resolve`. Use `--json` when you need structured values. + - **Inspect incoming preset**: `npx shadcn@latest preset decode `. Use `preset url ` or `preset open ` to share or open the preset builder. + - **Overwrite**: `npx shadcn@latest apply `. Overwrites detected components, fonts, and CSS variables. + - **Partial**: `npx shadcn@latest apply --only theme,font`. Updates only the selected preset parts without reinstalling UI components. Supported values are `theme` and `font`; comma-separated combinations are allowed. `icon` is intentionally not supported, because icon changes may require full component reinstall and transforms. + - **Merge**: `npx shadcn@latest init --preset --force --no-reinstall`, then run `npx shadcn@latest info` to list installed components, then for each installed component use `--dry-run` and `--diff` to [smart merge](#updating-components) it individually. + - **Skip**: `npx shadcn@latest init --preset --force --no-reinstall`. Only updates config and CSS, leaves components as-is. + - **Important**: Always run preset commands inside the user's project directory. `apply` only works in an existing project with a `components.json` file. The CLI automatically preserves the current base (`base` vs `radix`) from `components.json`. If you must use a scratch/temp directory (e.g. for `--dry-run` comparisons), pass `--base ` explicitly — preset codes do not encode the base. + +## Design Systems from DESIGN.md + +When the user asks for a design system from a `DESIGN.md` (or a brand spec), with or without a preset, follow [design-system.md](./design-system.md) end to end: + +1. `init --preset --template --name --no-monorepo -y`. Without a preset code, pick the closest style and pass `--base base --preset ,import './Card.css',Low,,astro 7.1.6,active,2026-08-13 +15,Styling,Use scoped styles by default,Astro scopes styles to component automatically, (scoped),,,Medium,,astro 7.1.6,active,2026-08-13 +17,Styling,Integrate Tailwind 4 through Vite,The Astro CLI configures Tailwind 4 with the official Vite plugin,Use astro add tailwind or configure @tailwindcss/vite,Add the deprecated @astrojs/tailwind integration,npx astro add tailwind,@astrojs/tailwind,Low,https://docs.astro.build/en/guides/styling/#tailwind,astro 7.1.6,active,2026-08-13 +18,Styling,Use CSS variables for theming,Define tokens in :root,CSS custom properties for themes,Hardcoded colors everywhere,:root { --primary: #3b82f6; },color: #3b82f6; everywhere,Medium,,astro 7.1.6,active,2026-08-13 +19,Data,Fetch in frontmatter,Data fetching in component frontmatter,Top-level await in frontmatter,useEffect for initial data,const data = await fetch(url),client-side fetch on mount,High,https://docs.astro.build/en/guides/data-fetching/,astro 7.1.6,active,2026-08-13 +20,Data,Use Astro.glob for local files,Import multiple local files,Astro.glob for markdown/data files,Manual imports for each file,const posts = await Astro.glob('./posts/*.md'),import post1; import post2;,Medium,,astro 7.1.6,active,2026-08-13 +21,Data,Prefer content collections over glob,Type-safe collections for structured content,getCollection() for blog/docs,Astro.glob for structured content,await getCollection('blog'),await Astro.glob('./blog/*.md'),High,https://docs.astro.build/en/guides/content-collections/,astro 7.1.6,active,2026-08-13 +22,Data,Use environment variables correctly,Import.meta.env for env vars,PUBLIC_ prefix for client vars,Expose secrets to client,import.meta.env.PUBLIC_API_URL,import.meta.env.SECRET in client,High,https://docs.astro.build/en/guides/environment-variables/,astro 7.1.6,active,2026-08-13 +23,Performance,Preload critical assets,Use link preload for important resources,Preload fonts above-fold images,No preload hints,"",No preload for critical assets,Medium,,astro 7.1.6,active,2026-08-13 +24,Performance,Optimize images with astro:assets,Built-in image optimization, component for optimization, for local images,import { Image } from 'astro:assets';,"",High,https://docs.astro.build/en/guides/images/,astro 7.1.6,active,2026-08-13 +25,Performance,Use picture for responsive images,Multiple formats and sizes, for art direction,Single image size for all screens, with multiple sources, with single size,Medium,,astro 7.1.6,active,2026-08-13 +26,Performance,Lazy load below-fold content,Defer loading non-critical content,loading=lazy for images client:visible for components,Load everything immediately,"",No lazy loading,Medium,,astro 7.1.6,active,2026-08-13 +27,Performance,Minimize client directives,Each directive adds JS bundle,Audit client: usage regularly,Sprinkle client:load everywhere,Only interactive components hydrated,Every component with client:load,High,https://docs.astro.build/en/reference/directives-reference/#client-directives,astro 7.1.6,active,2026-08-13 +28,ViewTransitions,Use ClientRouter for client-side transitions,Enable Astro client-side routing and transition fallbacks with the current component, in the shared head,Use removed ,import { ClientRouter } from 'astro:transitions';,,Medium,https://docs.astro.build/en/guides/view-transitions/,astro 7.1.6,active,2026-08-13 +29,ViewTransitions,Use transition:name,Named elements for morphing,transition:name for persistent elements,Unnamed transitions,"
",
without name,Low,,astro 7.1.6,active,2026-08-13 +30,ViewTransitions,Handle transition:persist,Keep state across navigations,transition:persist for media players,Re-initialize on every navigation,"
- - - - - - - - - - - -``` - ---- - -## 🛠️ 4. Catatan Implementasi untuk Agent Frontend (Next.js / React) - -Saat menerjemahkan kode di atas ke dalam struktur komponen React atau Next.js: - -1. **Leaflet.js di Next.js (SSR Handling)**: - Ingat bahwa pustaka Leaflet.js membutuhkan objek `window` global. Selalu impor komponen Peta secara dinamis menggunakan `dynamic()` Next.js dengan opsi `ssr: false`: - ```javascript - import dynamic from 'next/dynamic'; - const MapComponent = dynamic(() => import('@/components/MapComponent'), { ssr: false }); - ``` -2. **Tailwind Custom Colors**: - Masukkan warna identitas RekaKarbon ke dalam file konfigurasi `tailwind.config.js` Anda: - ```javascript - theme: { - extend: { - colors: { - 'rekakarbon': { - green: '#003E29', - mint: '#00C48C', - dark: '#002D1E', - } - } - } - } - ``` -3. **Animasi SVG & Progress Bar**: - Gunakan library transisi seperti `framer-motion` untuk menghidupkan grafik denda berjalan (SVG line) dan progress bar neraca karbon agar tampak sangat responsif saat data diunggah asinkron. - ---- - -## 🏗️ 5. Standar Arsitektur Frontend RekaKarbon (React + Tailwind CSS v4 + Zustand) - -Agar pengembang atau Agent kecerdasan buatan selanjutnya dapat berkontribusi secara konsisten dan menjaga kualitas kode, berikut adalah standar arsitektur frontend yang **wajib diikuti**: - -### 📁 5.1 Struktur Direktori Utama - -Kode frontend utama berada di bawah `/client`. Struktur direktori yang direkomendasikan adalah sebagai berikut: - -- [components/](file:///home/mashupsoat/Project/rekakarbon/RekaKarbon/client/src/components/): Komponen UI modular yang dapat digunakan kembali (contoh: [MapCanvas.jsx](file:///home/mashupsoat/Project/rekakarbon/RekaKarbon/client/src/components/MapCanvas.jsx), [RightDrawer.jsx](file:///home/mashupsoat/Project/rekakarbon/RekaKarbon/client/src/components/RightDrawer.jsx), [NDVIGauge.jsx](file:///home/mashupsoat/Project/rekakarbon/RekaKarbon/client/src/components/NDVIGauge.jsx), dll.). -- [data/](file:///home/mashupsoat/Project/rekakarbon/RekaKarbon/client/src/data/): Data statis yang digunakan platform (seperti proyek konservasi, perusahaan CEMS). -- [store/](file:///home/mashupsoat/Project/rekakarbon/RekaKarbon/client/src/store/): Toko state global (Zustand) seperti [useCarbonStore.js](file:///home/mashupsoat/Project/rekakarbon/RekaKarbon/client/src/store/useCarbonStore.js). -- [styles/](file:///home/mashupsoat/Project/rekakarbon/RekaKarbon/client/src/styles/): Gaya global (Tailwind CSS v4) di [index.css](file:///home/mashupsoat/Project/rekakarbon/RekaKarbon/client/src/styles/index.css). -- [utils/](file:///home/mashupsoat/Project/rekakarbon/RekaKarbon/client/src/utils/): Helper fungsional dan utilitas perhitungan geodetik/Shoelace. -- [App.jsx](file:///home/mashupsoat/Project/rekakarbon/RekaKarbon/client/src/App.jsx): Mengintegrasikan client-side routing dan modul portal utama. - -### 🔄 5.2 Manajemen State Global (Zustand Store) - -Semua state interaktif (navigasi modul, pilihan koordinat, data aktif, serta penanganan buka/tutup drawer) dikelola terpusat di [useCarbonStore.js](file:///home/mashupsoat/Project/rekakarbon/RekaKarbon/client/src/store/useCarbonStore.js). - -- **Aturan**: Jangan mencampur state lokal di dalam komponen jika data tersebut mempengaruhi Leaflet Map atau modul tetangga. Gunakan Zustand untuk koordinasi lintas-komponen yang bersih. - -### 🧭 5.3 Navigasi Kontrol - -- **PENTING**: Layout utama **tidak menggunakan sidebar kiri permanen**. -- Navigasi publik (Modul 1: Peta Konservasi & dMRV vs Modul 2: Emisi Perusahaan) dialihkan ke **Sliding Drawer dari sisi kanan** ([RightDrawer.jsx](file:///home/mashupsoat/Project/rekakarbon/RekaKarbon/client/src/components/RightDrawer.jsx)) yang dipicu oleh tombol "Menu Kontrol" di sudut kanan atas header. - -### 🎨 5.4 Tailwind CSS v4 & Tema - -Tailwind CSS v4 dikonfigurasi melalui `@theme` direktif di dalam [index.css](file:///home/mashupsoat/Project/rekakarbon/RekaKarbon/client/src/styles/index.css). - -- Desain warna primer adalah `#003E29` (`brand green`) dan aksen mint `#00C48C` (`accent mint`). - ---- - -_Dokumen Spesifikasi ini diperbarui untuk mencakup standar arsitektur modular produksi RekaKarbon._ diff --git a/client/DESIGN.md b/client/DESIGN.md index 52ad366..6013c1a 100644 --- a/client/DESIGN.md +++ b/client/DESIGN.md @@ -1,112 +1,103 @@ --- name: Ecological Precision +description: Semantic Design System & UI/UX Intelligence Specification for RekaKarbon Frontend colors: - surface: '#f8f9ff' - surface-dim: '#cbdbf5' - surface-bright: '#f8f9ff' - surface-container-lowest: '#ffffff' - surface-container-low: '#eff4ff' + # Primary Brand Identity (12-step Botanical Gradient & Solid Midpoints) + primary: '#033c2e' + primary-dark: '#022c22' + primary-light: '#034a38' + primary-gradient: 'linear-gradient(to right, #022c22, #022f24, #023126, #023428, #02372a, #02392c, #033c2e, #033f30, #034232, #034434, #034736, #034a38)' + primary-tint: 'rgba(3, 60, 46, 0.08)' + + # High-Tech Accents & Ecological Indicators + tech-mint: '#00c48c' + primary-container: '#10b981' + on-primary-container: '#00422b' + + # Surfaces, Canvas & Elevation + surface: '#ffffff' + surface-alt: '#f8fafc' surface-container: '#e5eeff' surface-container-high: '#dce9ff' surface-container-highest: '#d3e4fe' - on-surface: '#0b1c30' - on-surface-variant: '#3c4a42' - inverse-surface: '#213145' - inverse-on-surface: '#eaf1ff' - outline: '#6c7a71' - outline-variant: '#bbcabf' - surface-tint: '#006c49' - primary: '#006c49' - on-primary: '#ffffff' - primary-container: '#10b981' - on-primary-container: '#00422b' - inverse-primary: '#4edea3' - secondary: '#565e74' - on-secondary: '#ffffff' - secondary-container: '#dae2fd' - on-secondary-container: '#5c647a' - tertiary: '#a43a3a' - on-tertiary: '#ffffff' - tertiary-container: '#fc7c78' - on-tertiary-container: '#711419' - error: '#ba1a1a' - on-error: '#ffffff' - error-container: '#ffdad6' - on-error-container: '#93000a' - primary-fixed: '#6ffbbe' - primary-fixed-dim: '#4edea3' - on-primary-fixed: '#002113' - on-primary-fixed-variant: '#005236' - secondary-fixed: '#dae2fd' - secondary-fixed-dim: '#bec6e0' - on-secondary-fixed: '#131b2e' - on-secondary-fixed-variant: '#3f465c' - tertiary-fixed: '#ffdad7' - tertiary-fixed-dim: '#ffb3af' - on-tertiary-fixed: '#410005' - on-tertiary-fixed-variant: '#842225' - background: '#f8f9ff' - on-background: '#0b1c30' - surface-variant: '#d3e4fe' - surface-alt: '#F8FAFC' - pure-white: '#FFFFFF' + + # Typography, Hierarchy & Neutral Borders + on-surface: '#0f172a' + on-surface-variant: '#64748b' + text-primary: '#0f172a' + text-secondary: '#64748b' + border: '#e2e8f0' + outline: '#cbd5e1' + + # Semantic Regulatory & Fiscal Alert Tokens + status-success-bg: '#ecfdf5' + status-success-fg: '#065f46' + status-warning-bg: '#fffbeb' + status-warning-fg: '#92400e' + status-danger-bg: '#fff1f2' + status-danger-fg: '#9f1239' + status-danger-border: '#fecdd3' + + # Alert Semantics + danger-red: '#ef4444' + warning-orange: '#f59e0b' + verified-mint: '#00c48c' + typography: + font-family: "'Plus Jakarta Sans', 'Inter', system-ui, sans-serif" headline-xl: - fontFamily: Plus Jakarta Sans - fontSize: 48px - fontWeight: '700' - lineHeight: 56px - letterSpacing: -0.02em - headline-xl-mobile: - fontFamily: Plus Jakarta Sans - fontSize: 32px - fontWeight: '700' - lineHeight: 40px + fontSize: 36px + fontWeight: '800' + lineHeight: 44px letterSpacing: -0.02em headline-lg: - fontFamily: Plus Jakarta Sans fontSize: 30px - fontWeight: '600' + fontWeight: '700' lineHeight: 38px letterSpacing: -0.01em headline-md: - fontFamily: Plus Jakarta Sans fontSize: 24px - fontWeight: '600' + fontWeight: '700' lineHeight: 32px + headline-sm: + fontSize: 20px + fontWeight: '600' + lineHeight: 28px body-lg: - fontFamily: Plus Jakarta Sans fontSize: 18px fontWeight: '400' lineHeight: 28px body-md: - fontFamily: Plus Jakarta Sans fontSize: 16px fontWeight: '400' lineHeight: 24px body-sm: - fontFamily: Plus Jakarta Sans fontSize: 14px fontWeight: '400' lineHeight: 20px label-md: - fontFamily: Plus Jakarta Sans fontSize: 14px fontWeight: '600' lineHeight: 20px letterSpacing: 0.05em label-sm: - fontFamily: Plus Jakarta Sans fontSize: 12px - fontWeight: '500' + fontWeight: '600' lineHeight: 16px + letterSpacing: 0.025em + metric-stat: + fontSize: 28px + fontWeight: '800' + lineHeight: 36px + rounded: - sm: 0.25rem + sm: 0.375rem DEFAULT: 0.5rem md: 0.75rem lg: 1rem xl: 1.5rem full: 9999px + spacing: base: 4px xs: 4px @@ -120,46 +111,145 @@ spacing: gutter: 24px --- -## Brand & Style +# Ecological Precision — Frontend Design System & AI Agent Specification + +This specification synthesizes the **Semantic Design System** (following Google Stitch `design-md` conventions) with **UI/UX Design Intelligence** (following `ui-ux-pro-max` industry best practices). + +All AI agents and frontend developers implementing screens in **RekaKarbon Client** (`client/`) MUST adhere strictly to these tokens, geometry, accessibility standards, and component patterns. + +--- + +## 🌿 1. Visual Theme & Atmosphere + +- **Aesthetic Philosophy**: **Ecological Precision** merges biophilic sustainability with scientific precision and Swiss modernism. The interface communicates high-integrity institutional verification (carbon accounting, dMRV spatial telemetry, blockchain ledger audit trails) without feeling sterile or archaic. +- **Mood & Atmosphere**: _Data-Dense, Trustworthy, Crisp, Optimistic, and Utilitarian_. +- **Surface Strategy**: Rather than relying on muddy, heavy drop shadows, elevation is achieved via **clean tonal layering**: + - The page canvas rests on **Soft Alpine Slate (`#F8FAFC`)**. + - Interactive cards and containers emerge in **Crisp Pure White (`#FFFFFF`)** bound by a razor-thin, low-contrast 1px border (`#E2E8F0`). + - Active overlays, tooltips, and badges utilize **Whisper-Soft Ambient Diffusion** (`rgba(15, 23, 42, 0.06)`). + +--- + +## 🎨 2. Color Palette & Functional Roles -The design system is rooted in the intersection of environmental sustainability and data-driven precision. It targets eco-conscious enterprises and individual climate advocates who require a professional, trustworthy, and optimistic interface to manage carbon footprints. +Colors are mapped semantically to avoid raw hex code sprawl in component JSX/TSX. -The visual style is **Corporate Modern with a Minimalist edge**. It leverages high-quality white space, a focused palette of botanical greens against deep slate, and precise geometric typography. The aesthetic avoids "grungy" eco-stereotypes in favor of a clean, high-tech laboratory feel that communicates reliability and modern environmental science. +| Descriptive Name | Hex / CSS Class | Functional Role | UX Guidelines & Contrast | +| :---------------------------------------- | :------------------------------------------------ | :------------------------------------------------------------------ | :----------------------------------------------------------------------------------- | +| **Deep Botanical Canopy (Primary Solid)** | `#033C2E`
`var(--color-primary)` | Solid headings, active portal links, dark border accents | High contrast (>7:1 on white). Never substitute with deprecated `#003E29`. | +| **12-Step Forest Gradient** | `#022C22` → `#034A38`
`.bg-primary-gradient` | Primary CTA buttons, brand banners, key metric header titles | Represents depth and living forest density. Paired with white text. | +| **Bio-Tech Mint (Accent)** | `#00C48C`
`var(--color-tech-mint)` | Verified badges, GIS sensor pulse markers, dMRV indicators | Accent & visual indicator. When used as text, ensure dark background or bold stroke. | +| **Obsidian Slate (Text Primary)** | `#0F172A`
`text-slate-900` | Primary page headers, metric figures, table content | Highest visual weight (>12:1 contrast ratio against white/surface). | +| **Muted Lichen (Text Secondary)** | `#64748B`
`text-slate-500` | Explanatory subtext, timestamp notes, table headers | Meets WCAG AA (4.5:1 on white). Never use lighter than `#64748B` for body copy. | +| **High-Carbon Scarlet (Danger/Deficit)** | `#EF4444`
`text-[#EF4444]` / `bg-rose-50` | Emission quota deficits, fiscal tax liabilities, irreversible burns | Critical alert state. Always pair with descriptive text + icon (never color alone). | +| **Amber Caution (Warning/Pending)** | `#F59E0B`
`text-[#F59E0B]` / `bg-amber-50` | Low token supply, pending dMRV audits, reversible alerts | Warns user of impending limits or required review. | +| **Canopy Mint (Verified Status)** | `#10B981`
`text-emerald-700` / `bg-emerald-50` | Net-zero compliance, validated smart contract notarization | Indicates successful cryptographic verification. | +| **Soft Alpine Canvas** | `#F8FAFC`
`bg-slate-50` | Global view canvas background | Cool neutral backdrop reducing eye strain during analytical review. | +| **Pure White Container** | `#FFFFFF`
`bg-white` | Dashboard metric cards, data tables, modals, sidebars | Primary foreground container surface. | -## Colors +--- -The palette is dominated by **Emerald Green (#10B981)**, symbolizing growth and ecological health. This is anchored by **Deep Slate (#0F172A)** for high-contrast text and structural elements, ensuring professional authority. +## 📐 3. Geometry, Shapes & Depth -**Slate Gray (#64748B)** is used for secondary information and borders to maintain a soft but technical appearance. The background strategy utilizes **Surface Alt (#F8FAFC)** for subtle section nesting and **Pure White (#FFFFFF)** for primary content cards to create a sense of depth through slight tonal shifts. +Technical Tailwind radius classes translated to tactile physical form: -## Typography +- **Subtly Rounded Precision Cards (`rounded-xl` / `0.75rem` / `12px`)**: Applied to all primary KPI stat containers, data tables, and modal dialogs. Softens institutional geometry while preserving clean vertical alignment. +- **Pill-Shaped Status Badges (`rounded-full`)**: Used for verification tags, network status badges (`Live - Mainnet`), and filter chips. +- **Tactile Interactive Buttons (`rounded-xl` / `12px`)**: Primary and secondary buttons feature smooth corners with a minimum tap target of **44×44px** to satisfy mobile/tablet touch usability. +- **Crisp Focus Rings (`focus-visible:ring-2 focus-visible:ring-primary/20`)**: Keyboard accessibility is strictly enforced; focus rings are never removed with `outline-none` unless accompanied by a high-contrast replacement ring. -This design system utilizes **Plus Jakarta Sans** as its primary typeface. It is chosen for its modern, friendly, and geometric characteristics that bridge the gap between "approachable" and "professional." +--- -Headlines use a tighter letter-spacing and heavier weights to create impact, while body text maintains generous line-heights for readability in data-heavy contexts. For specialized data displays or numerical carbon values, a fallback to system monospaced fonts may be used to emphasize technical accuracy. +## 🔤 4. Typography & Visual Hierarchy -## Layout & Spacing +- **Typeface**: **`Plus Jakarta Sans`** (primary UI & headings) paired with **`Inter`** (data-dense tables & numerical fallbacks). +- **Scale & Rhythms**: + - **Metric Hero**: `text-3xl` / `font-extrabold` (36px, tracking tight) for primary carbon tonnage and fiscal amounts. + - **Section Titles**: `text-xl` or `text-2xl` / `font-bold` (20–24px) with `text-[#033C2E]`. + - **Body Copy**: `text-sm` (14px) with `leading-relaxed` (line-height 1.5–1.6) in `text-slate-600`. + - **Captions & Metadata**: `text-xs` (12px) / `font-semibold` with uppercase letter-spacing (`tracking-wider`) for labels and tags. +- **Rule of Numbers**: All currency (IDR), carbon tonnages (tCO₂e), areas (ha), and percentages MUST be formatted via centralized formatters in `src/lib/formatters.ts`. Never display raw unformatted floats. -The layout follows a **Fluid Grid** system with a maximum container width of 1280px for desktop. It utilizes a 12-column structure on desktop, 8-column on tablet, and a single-column flow on mobile. +--- -Spacing is governed by a 4px base unit. Internal card padding is consistently set at `lg` (24px) to ensure content has breathing room. Section vertical rhythm follows a `3xl` (64px) margin to clearly delineate the narrative flow. +## 🧩 5. Component Construction & UI Hierarchy (`shadcn/ui` First) + +When translating feature requirements to components, agents must follow this strict composition hierarchy and CLI conventions: + +### CLI & Installation Rule + +- When adding new UI primitives from registry, always use: + ```bash + pnpm dlx shadcn@latest add + ``` +- Always verify installed components in `@/components/ui/` before introducing new components. + +### 1. Primitive Elements (`@/components/ui/`) + +- **Buttons (`Button`)**: + - Primary CTA: `className="bg-primary-gradient text-white hover:bg-primary-gradient-dark shadow-sm min-h-[44px]"` + - Secondary: `variant="outline" className="border-slate-200 text-slate-700 hover:bg-slate-50 min-h-[44px]"` + - High-Risk Action (Burn/Offset): `variant="destructive" className="bg-red-600 hover:bg-red-700 text-white min-h-[44px]"` + - Loading State: Compose with `` and `disabled={isLoading}` (Button does not have an `isLoading` prop). +- **Cards (`Card`)**: + - Must use full semantic Card composition: ``, ``, ``, ``, ``. Do not dump all markup directly into ``. +- **Structured Tables (`Table`)**: + - Must use full semantic tree: ``, ``, ``, ``, ``, ``. + - Never replace tabular data with unsemantic `
` elements. +- **Overlays (`Dialog`, `Sheet`, `Drawer`)**: + - **Mandatory Accessibility Title**: ``, ``, or `` is strictly required. If visually hidden, apply `className="sr-only"`. + - **No Manual Z-Index**: Never manually assign `z-50` or `z-[999]` to overlays; primitives manage their own stacking context. +- **Callouts & Skeletons**: + - Callouts MUST use `` and `` (never custom-styled colored divs). + - Loading placeholders MUST use `` (never custom `animate-pulse` divs). + - Dividers MUST use `` (never raw `
` or `
`). +- **Styling Discipline**: + - **Equal Dimensions**: Always use `size-*` instead of `w-* h-*` (e.g., `size-10`, `size-4`). + - **Flex Gap**: Always use `flex flex-col gap-4` or `flex gap-2`. Never use legacy `space-y-*` or `space-x-*`. + - **Class Utilities**: Use `cn()` from `@/lib/utils` for conditional classes; never manual template literal string concatenation. + +### 2. Standard Layout Containers (`@/components/layout/`) + +- **`PageHeader`**: Consistent title, contextual subtitle, and action button slots. +- **`KpiStatCard`**: Standardized metric presentation with icon, delta indicator, and comparative context. +- **`FilterToolbar`**: Unified search input, role filters, date range picks, and export button slots. +- **`PortalSidebar` & `PortalLayout`**: Multi-role authenticated application frame with role-tailored navigation items. -## Elevation & Depth +--- -Depth is primarily established through **Tonal Layers** rather than heavy shadows. The background uses `#F8FAFC`, while interactive or focal containers use `#FFFFFF`. +## ♿ 6. Accessibility & Usability Invariants (WCAG 2.1 AA) -When elevation is required (e.g., modals or floating buttons), use an **Ambient Shadow**: a very soft, diffused shadow with a subtle tint of the secondary color (`rgba(15, 23, 42, 0.08)`). For most cards and input fields, a **Low-contrast Outline** using a 1px border of `#E2E8F0` (a lighter tint of the neutral color) is preferred over shadows to maintain the minimalist, clean aesthetic. +1. **Color Independence**: Color MUST NEVER be the sole conveyor of state. + - Deficit states must show red badge **plus** `AlertTriangle` icon **plus** text `Defisit: 2.330 tCO2e`. + - Verified status must show mint background **plus** `ShieldCheck` icon **plus** text `Terverifikasi dMRV`. +2. **Accessible Click Targets**: All interactive targets (buttons, icon triggers, table action menus) must be at least **44×44px** in tappable area. +3. **Screen Reader Discipline**: All icon-only buttons (``) MUST include `aria-label="Lihat Detail"` or `Lihat Detail`. +4. **Focus Trapping**: Modals, Dialogs, and Sliding Drawers must trap focus and close cleanly on `Escape` keypress. -## Shapes +--- + +## ⚡ 7. Micro-Interactions, Motion & Feedback -The shape language is **Rounded**, reflecting the organic nature of the sustainability theme while maintaining architectural order. +1. **Context-Aware Timing**: + - Micro-interactions (hover, active tab, focus ring): **150ms–200ms** with `ease-out`. + - Drawer slide & sheet transitions: **300ms** with smooth cubic bezier. + - Exit transitions must be faster than entrance transitions (e.g. 150ms exit vs 200ms enter). +2. **Action Feedback**: + - Every async mutation button (Beli Token, Bakar Token, Unggah Dokumen) MUST display a disabled spinner state (``) while execution is pending. +3. **Respect Reduced Motion**: + - Use Tailwind's `motion-safe:` or ensure high-motion effects degrade gracefully when `prefers-reduced-motion` is active. + +--- -Standard components like buttons and inputs use a 0.5rem (8px) radius. Larger containers and cards use `rounded-lg` (16px) to create a softer, more modern framing for content. This consistent rounding across the system softens the precision of the grid and makes the data feel more accessible. +## 🛡️ 8. Error Prevention & High-Risk Protocols (Heuristic #5) -## Components +In institutional carbon accounting, accidental state mutations carry financial and legal penalties: -- **Buttons:** Primary buttons use the Primary Emerald Green with white text and a subtle hover scale effect. Secondary buttons use a Slate outline with a transparent background. All buttons should have a minimum height of 44px for accessibility. -- **Input Fields:** Use a white background with a 1px border of Slate-200. On focus, the border shifts to Emerald Green with a 2px outer glow of the same color at 10% opacity. -- **Cards:** Cards should be white with a 1px border. Avoid heavy shadows; instead, use a subtle vertical offset on hover to indicate interactivity. -- **Chips/Badges:** Use low-saturation backgrounds derived from the primary color (e.g., a 10% opacity green) with high-saturation text for status indicators. -- **Progress Bars:** Representing carbon metrics, these should use the Primary Green for positive/neutral data and a named "Warning Orange" or "Error Red" only for critical carbon overages. +1. **Burning Chamber / Retirement Protocol**: + - Real-time conversion formula: **`10 fractions = 1.0 tCO2e`**. + - Irreversible Action: Burning tokens removes them from the circulating supply permanently. + - UI Requirement: Red/Amber warning styling, secondary confirmation modal, and explicit summary of tonnes to be retired. +2. **Cap Control Market Purchasing**: + - Emitters must be prevented or explicitly warned from submitting purchase orders exceeding their verified deficit (e.g. 2,330 tCO₂e) to avoid speculative market hoarding. +3. **dMRV Transparency Affordance**: + - Every metric backed by satellite or drone verification must render a direct link or modal trigger: `Verifikasi Sumber Data dMRV`. diff --git a/skills-lock.json b/skills-lock.json index bb6ee94..5d2223b 100644 --- a/skills-lock.json +++ b/skills-lock.json @@ -1,6 +1,12 @@ { "version": 1, "skills": { + "design-md": { + "source": "google-labs-code/stitch-skills", + "sourceType": "github", + "skillPath": "plugins/stitch-utilities/skills/design-md/SKILL.md", + "computedHash": "44af3e6e89a42a765d9cebf943f1e2ff3cdf43d1958341eb43fb7b74116f6691" + }, "javascript-testing-patterns": { "source": "wshobson/agents", "sourceType": "github", @@ -66,6 +72,18 @@ "sourceType": "github", "skillPath": ".agents/skills/react-router/SKILL.md", "computedHash": "38cfa0037d15717ebcaa412b9cb950941564b5f658b40344652ef6634a28dd28" + }, + "shadcn": { + "source": "shadcn-ui/ui", + "sourceType": "github", + "skillPath": "skills/shadcn/SKILL.md", + "computedHash": "2d7bf36e581289fdcc3ffc592c1ec1d7457572baa72ba0d440229ef34bd7f6dd" + }, + "ui-ux-pro-max": { + "source": "nextlevelbuilder/ui-ux-pro-max-skill", + "sourceType": "github", + "skillPath": ".claude/skills/ui-ux-pro-max/SKILL.md", + "computedHash": "7ac62d931e52dbc7c309ed8ee067101969db2454709339b02daa583e80e98d5f" } } } From b83b16f3cd5f500e8ce7586ab85f537f11c3ec94 Mon Sep 17 00:00:00 2001 From: Farrel Augusta Dinata Date: Sun, 11 Oct 2026 19:01:13 +0700 Subject: [PATCH 3/3] docs: update contributing guide to this project --- .github/ISSUE_TEMPLATE/bug_report.yml | 82 +++++ .github/ISSUE_TEMPLATE/config.yml | 11 + .github/ISSUE_TEMPLATE/feature_request.yml | 56 ++++ CODE_OF_CONDUCT.md | 122 +++++++ CONTRIBUTING.md | 363 ++++++++++++++++++--- 5 files changed, 582 insertions(+), 52 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 CODE_OF_CONDUCT.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..66231a5 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,82 @@ +name: 🐛 Bug Report +description: Report a reproducible software defect or unexpected behavior in RekaKarbon +title: 'bug: ' +labels: ['bug', 'triage'] +body: + - type: markdown + attributes: + value: | + Thank you for reporting a bug! Please ensure you have searched existing issues before submitting. + - type: dropdown + id: component + attributes: + label: Affected Subproject / Component + description: Select the primary module or package where the bug occurs. + options: + - 'client (Frontend / React Router / UI)' + - 'server (Backend / NestJS / API)' + - 'server/prisma (Database & Migrations)' + - 'blockchain (Smart Contracts / Besu / Hardhat)' + - 'ml (AI Engine / Feature Extractor / ONNX)' + - 'gis (Spatial Data / GeoTIFF / Vector Tiles)' + - 'ci-cd (GitHub Actions / Tooling / Scripts)' + - 'documentation (Docs / AGENTS.md / Specs)' + validations: + required: true + - type: textarea + id: description + attributes: + label: Bug Description + description: A clear and concise description of what the bug is. + placeholder: Describe the problem encountered... + validations: + required: true + - type: textarea + id: reproduction + attributes: + label: Steps to Reproduce + description: What sequence of steps leads to the error? + placeholder: | + 1. Start application with `pnpm dev` + 2. Navigate to portal route `/emitter/bursa` + 3. Attempt to submit an order with ... + 4. See error ... + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected Behavior + description: What did you expect to happen instead? + placeholder: The transaction order should validate and trigger the confirmation dialog... + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual Behavior + description: What actually occurred? + placeholder: The application crashed with 500 error / unhandled rejection... + validations: + required: true + - type: textarea + id: environment + attributes: + label: Environment & System Details + description: Operating system, browser, Node version, Docker version, etc. + value: | + - OS: [e.g. Windows 11, Ubuntu 24.04, macOS 15] + - Node Version: [e.g. 24.15.0] + - pnpm Version: [e.g. 11.22.0] + - Browser: [e.g. Chrome 126, Firefox 128] + - Environment Flags: [e.g. VITE_USE_MOCK_DATA=true] + validations: + required: false + - type: textarea + id: logs + attributes: + label: Relevant Logs or Screenshots + description: Paste stack traces, terminal output, or browser console errors here. + render: shell + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..b30b36c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: 💬 Questions & Community Support + url: https://github.com/SYNETRATECH/RekaKarbon/discussions + about: Please ask general support, deployment, and architecture questions here. + - name: 🔒 Security Vulnerability Report + url: https://github.com/SYNETRATECH/RekaKarbon/security/policy + about: Review our security policy and report vulnerabilities privately. + - name: 📖 AI Agent & Technical Documentation + url: https://github.com/SYNETRATECH/RekaKarbon/blob/main/AGENTS.md + about: Explore technical architecture and AI agent governance guides. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..9b39b6d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,56 @@ +name: 🚀 Feature Request +description: Propose a new feature, improvement, or functional enhancement for RekaKarbon +title: 'feat: ' +labels: ['enhancement', 'proposal'] +body: + - type: markdown + attributes: + value: | + Thank you for suggesting a feature! Please describe your proposal and use case in detail. + - type: dropdown + id: component + attributes: + label: Target Subproject / Component + description: Which part of the platform would this enhancement affect? + options: + - 'client (Frontend / React Router / UI)' + - 'server (Backend / NestJS / API)' + - 'server/prisma (Database Schema & Queries)' + - 'blockchain (Smart Contracts / Besu / Protocol)' + - 'ml (AI Engine / Feature Extractor / ONNX)' + - 'gis (Spatial Data / Remote Sensing)' + - 'ci-cd (GitHub Actions / Developer Tooling)' + - 'monorepo-wide (Multi-component architecture)' + validations: + required: true + - type: textarea + id: problem + attributes: + label: Problem Statement / Context + description: Is your feature request related to a problem or institutional workflow gap? + placeholder: As an auditor / emitter, I need to ... because currently ... + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed Solution & Specifications + description: Describe the solution you would like to see implemented. + placeholder: Detailed description of the UI, API endpoint, or smart contract logic... + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternative Approaches Considered + description: Have you considered any alternative solutions or workarounds? + placeholder: Describe alternatives explored... + validations: + required: false + - type: textarea + id: additional + attributes: + label: Additional Context & Regulatory Alignment + description: Any regulatory citations (e.g. UU No. 7/2021 HPP, Perpres 98/2021), mockups, or extra notes. + validations: + required: false diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..6d2a912 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,122 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +- Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery, and sexual attention or advances of + any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email + address, without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +[security@rekakarbon.id](mailto:security@rekakarbon.id) or by contacting repository maintainers. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html). + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0f11f05..14a974e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,86 +1,345 @@ -# Contributing Guidelines - RekaKarbon Monorepo +# Contributing to RekaKarbon Monorepo -Welcome to **RekaKarbon**! This guide outlines the development standards, code conventions, and workflows required when contributing to this repository. +Welcome to the **RekaKarbon** repository! We are excited to collaborate with open-source contributors, institutional partners, and autonomous AI agents to build Indonesia's high-integrity digital carbon MRV and compliance trading platform. + +This guide defines the end-to-end development standards, git workflows, architectural boundaries, and quality gates expected from every contributor. --- -## 🛠️ 1. Code Naming & Style Conventions +## 📋 Table of Contents -All code contributed to `@client` and `@server` must adhere to these standard conventions: +- [Code of Conduct](#-code-of-conduct) +- [Questions & Support](#-questions--support) +- [Reporting Issues](#-reporting-issues) + - [Submitting a Bug Report](#submitting-a-bug-report) + - [Proposing a Feature](#proposing-a-feature) + - [Security Vulnerabilities](#security-vulnerabilities) +- [Pull Request (PR) Workflow](#-pull-request-pr-workflow) +- [Monorepo Development Setup](#-monorepo-development-setup) + - [Prerequisites](#prerequisites) + - [Dependency Installation](#dependency-installation) + - [Running the Applications Locally](#running-the-applications-locally) + - [Environment Variables & Zero Secrets](#environment-variables--zero-secrets) + - [Database Management (Prisma ORM)](#database-management-prisma-orm) + - [Smart Contracts & Blockchain (Hardhat)](#smart-contracts--blockchain-hardhat) + - [Machine Learning Runtime (Poetry & ONNX)](#machine-learning-runtime-poetry--onnx) +- [Sub-Project Architecture & Coding Standards](#-sub-project-architecture--coding-standards) + - [1. Frontend / Client (`client/`)](#1-frontend--client-client) + - [2. Backend / Server (`server/`)](#2-backend--server-server) + - [3. Blockchain / Smart Contracts (`blockchain/`)](#3-blockchain--smart-contracts-blockchain) + - [4. Machine Learning & AI (`ml/`)](#4-machine-learning--ai-ml) +- [🤖 AI Agent Contribution Protocol](#-ai-agent-contribution-protocol) +- [Branch Naming Conventions](#-branch-naming-conventions) +- [Commit Message Guidelines](#-commit-message-guidelines) +- [Quality Gates & PR Verification Matrix](#-quality-gates--pr-verification-matrix) +- [Additional Resources](#-additional-resources) -| Category | Standard Convention | Example | -| ------------------------------- | ------------------------------ | --------------------------------------------------------------- | -| **Variables & Functions** | `camelCase` | `forestProjects`, `calculateGeodetics()`, `getProjectDetails()` | -| **React Components** | `PascalCase` | `CarbonDexMarket`, `ForestProjectsManagement`, `RightDrawer` | -| **Types & Interfaces** | `PascalCase` (in `src/types/`) | `Project`, `ForestProjectItem`, `AuthCredentials` | -| **Global Constants & Fixtures** | `UPPER_SNAKE_CASE` | `MOCK_BURSA_ITEMS`, `COMPANIES_DATA`, `VITE_USE_MOCK_DATA` | -| **React Hooks** | `camelCase` (`use` prefix) | `useCarbonStore` | +--- -### Type Centralization Standard +## 🤝 Code of Conduct -- **Location**: All domain interfaces and types MUST be declared inside [`client/src/types/`](client/src/types/) and re-exported via [`client/src/types/index.ts`](client/src/types/index.ts). -- **Prohibition**: Do NOT declare inline interface types inside mock data files (`src/lib/mock/*`) or view components (`src/portal/*`). +Help us foster a respectful, inclusive, and professional environment. All participants are required to follow our [Code of Conduct](./CODE_OF_CONDUCT.md). --- -## 🏗️ 2. Repository Pattern Workflow +## 💬 Questions & Support -When creating or modifying data features, follow the mandatory 4-step architecture: +Please **do not open GitHub issues for general support or architectural questions**. -1. **Type Interface**: Define the data structure in `client/src/types/.ts`. -2. **Static Mock Data**: Create strongly-typed static fixtures in `client/src/lib/mock/.ts`. -3. **Repository Abstraction**: Implement `Mock...Repository` and `Api...Repository` in `client/src/repositories/.repository.ts`, toggled by `VITE_USE_MOCK_DATA`. -4. **Zustand Store Integration**: Consume repository calls asynchronously inside `client/src/store/useCarbonStore.ts`. +- First consult the documentation: [AGENTS.md](./AGENTS.md), [README.md](./README.md), and [docs/](./docs/). +- For design system and token questions, see [client/DESIGN.md](client/DESIGN.md). +- For community support and discussion, use [GitHub Discussions](https://github.com/SYNETRATECH/RekaKarbon/discussions). --- -## ✅ 3. Local PR Verification & Quality Checks +## 🐛 Reporting Issues + +### Submitting a Bug Report + +Before opening an issue, check the [issue tracker](https://github.com/SYNETRATECH/RekaKarbon/issues) to avoid duplicate reports. + +When filing a bug, use the [Bug Report Form](.github/ISSUE_TEMPLATE/bug_report.yml) and specify: + +1. **Affected Subproject**: `client`, `server`, `server/prisma`, `blockchain`, `ml`, `gis`, or `ci-cd`. +2. **Clear Description**: Summary of the defect and context. +3. **Step-by-step Reproduction**: Minimal steps to trigger the bug. +4. **Expected vs Actual Behavior**. +5. **Environment Details**: OS, Node version, Docker version, browser, and feature flags (`VITE_USE_MOCK_DATA`). +6. **Logs & Stack Traces**. + +### Proposing a Feature + +If you would like to request or build a new feature, use the [Feature Request Form](.github/ISSUE_TEMPLATE/feature_request.yml): + +- For **major features** (e.g. new blockchain contracts, ML audit architectures, or regulatory portal flows), open an issue proposal first to coordinate design decisions before writing code. +- For **small improvements**, you may directly submit a Pull Request. + +### Security Vulnerabilities + +**NEVER report security vulnerabilities via public GitHub issues.** Follow our [Security Policy](./SECURITY.md) and report concerns directly to maintainers via [security@rekakarbon.id](mailto:security@rekakarbon.id). + +--- + +## 🚀 Pull Request (PR) Workflow + +1. **Fork & Branch**: Fork the repository (or create a branch on origin if you are a team member). +2. **Create a Topic Branch**: Use our standard [Branch Naming](#-branch-naming-conventions): + ```bash + git checkout -b feat/client/carbon-wallet-redesign main + ``` +3. **Develop & Verify**: Implement your changes and write automated tests. Run local verification for modified subprojects (see [Quality Gates](#-quality-gates--pr-verification-matrix)). +4. **Git Hygiene**: Keep commits atomic and informative. Follow [Commit Message Guidelines](#-commit-message-guidelines). +5. **Push & Open PR**: Push to GitHub and open a PR against `main`. Fill out the [Pull Request Template](.github/pull_request_template.md). +6. **Code Review & Rebase**: If changes are requested, apply them, re-run verification, and rebase on `main`: + ```bash + git fetch origin main + git rebase origin/main + git push --force-with-lease + ``` + +--- + +## 🛠️ Monorepo Development Setup + +RekaKarbon is an orchestrated polyglot monorepo: + +- **TypeScript Workspaces** (`client/`, `server/`, `blockchain/`) managed by **pnpm workspaces**. +- **Python ML Engine & Notifiers** (`ml/`, `scripts/actions/ci_notifier/`) managed by **Poetry**. +- **Hyperledger Besu QBFT** private blockchain network and local Docker infrastructure. + +### Prerequisites -Before submitting a Pull Request, verify that all local checks pass cleanly: +| Tool | Recommended Version | Purpose | +| :------------------- | :--------------------------------------------- | :-------------------------------------- | +| **Node.js** | `>= 24.15.0` (see [`.nvmrc`](.nvmrc)) | JavaScript runtime | +| **pnpm** | `11.22.0` (`packageManager` in `package.json`) | Monorepo package manager | +| **Python** | `>= 3.12` | Machine learning engine & scripts | +| **Poetry** | `>= 1.8.0` | Python dependency & virtualenv manager | +| **Docker & Compose** | Recent version | Local PostgreSQL, MinIO, and Besu nodes | + +### Dependency Installation + +```bash +# 1. Install Node.js dependencies across all workspaces +pnpm install + +# 2. Install Python ML dependencies in ml/ +poetry --directory ./ml install +``` + +### Running the Applications Locally ```bash -# Code Formatting (Prettier) -pnpm format:write +# Start both Backend (NestJS) and Frontend (Vite) concurrently +pnpm dev + +# Or run individual subprojects: +pnpm server:dev # NestJS backend on http://localhost:3000 +pnpm client:dev # React Router frontend on http://localhost:5173 +``` + +### Environment Variables & Zero Secrets + +- Every subproject provides a `.env.example` template: + - `client/.env.example` (`VITE_USE_MOCK_DATA=true`) + - `server/.env.example` (`DATABASE_URL`, `JWT_SECRET`, `RPC_URL`, `MINIO_*`) + - `blockchain/.env.example` (`BESU_RPC_URL`, `PRIVATE_KEY`) + - `ml/.env.example` +- Copy `.env.example` to `.env` in the target directory and populate local values. +- **ZERO SECRET LEAKS**: Never commit private keys, mnemonics, passwords, or `.env` files. Monorepo CI automatically blocks commits containing cryptographic secrets. -# TypeScript Typecheck -pnpm client:typecheck -pnpm server:typecheck +### Database Management (Prisma ORM) -# Linter Verification -pnpm client:lint +Database schemas are strictly managed through Prisma ORM migrations: -# Automated Unit & Architecture Tests -pnpm client:test -pnpm server:test +```bash +pnpm db:generate # Generate Prisma Client +pnpm db:migrate # Apply pending database migrations in development +pnpm db:seed # Seed database with initial roles & test datasets +pnpm db:studio # Open Prisma Studio visual web editor +``` + +### Smart Contracts & Blockchain (Hardhat) + +```bash +pnpm blockchain:compile # Compile Solidity contracts via Hardhat +pnpm blockchain:test # Run Hardhat smart contract test suite +pnpm blockchain:typecheck # Validate TypeChain bindings ``` -### Architecture Restrictions +### Machine Learning Runtime (Poetry & ONNX) -- Views (`src/components/`, `src/portal/`) are strictly forbidden from importing `src/lib/mock/*` directly. Access MUST go through `store` -> `repositories` -> `lib/mock`. +```bash +pnpm ml:lint # Lint Python code with Ruff +pnpm ml:typecheck # Type check Python models with MyPy +pnpm ml:test # Run Pytest suite & ONNX mathematical parity checks +``` --- -## 🔢 4. Data Formatting & Backend API Compatibility +## 🏛️ Sub-Project Architecture & Coding Standards + +### 1. Frontend / Client (`client/`) + +- **Stack**: React 19, React Router v7 (SSR), Zustand, Tailwind CSS v4. +- **Governance**: Follow [client/AGENTS.md](client/AGENTS.md) and [client/DESIGN.md](client/DESIGN.md). +- **Design Tokens**: Adhere to the **Ecological Precision** design system (12-step gradient `.bg-primary-gradient`, solid primary `#033C2E`, Tech Mint `#00C48C`). Do NOT use deprecated hardcoded `#003E29`. +- **UI First (`shadcn/ui`)**: Prioritize `@/components/ui/` primitives and `@/components/layout/` containers. When adding components, use `pnpm dlx shadcn@latest add `. +- **Repository Pattern**: View components (`routes/`, `components/`) must NEVER import `lib/mock` directly. Data must flow: `View` → `Zustand Store` → `Repository` → `Mock / API Client`. Enforced by `pnpm client:test` architecture tests. +- **Data Formatting**: Domain interfaces and mocks store raw numeric values and ISO dates. Formatting (`formatCurrency`, `formatCarbon`, `formatDate`) occurs dynamically at render time. +- **Geodetic Math**: Spatial area calculations must use `src/utils/geodetics.ts`. + +### 2. Backend / Server (`server/`) -To ensure seamless integration with strict backend APIs (PostgreSQL, REST, GraphQL), all data models and presentation layers must adhere to these standards: +- **Stack**: NestJS 11+, TypeScript, Prisma ORM 7, PostgreSQL, MinIO S3 SDK. +- **Governance**: Follow [server/AGENTS.md](server/AGENTS.md). +- **API Envelope**: All REST endpoints must return standardized JSON envelopes: + ```json + { + "success": true, + "data": { ... }, + "meta": { "timestamp": "2026-02-14T08:00:00.000Z" } + } + ``` +- **Security & RBAC**: Every endpoint must be protected with `JwtAuthGuard` and role-restricted using `RolesGuard` matching one of the 4 defined portals (`KTH`, `EMITTER`, `AUDITOR`, `REGULATOR`). +- **DTO Validation**: Incoming payloads must use `class-validator` and `class-transformer` with `ValidationPipe({ whitelist: true, forbidNonWhitelisted: true })`. -### Data Model Rules (`client/src/types/` & `client/src/lib/mock/`) +### 3. Blockchain / Smart Contracts (`blockchain/`) -- **Raw Numbers**: Monetary amounts, carbon tonnage, land areas, and file sizes MUST be stored as raw numeric values (e.g. `200000000`, `48200`, `2450`, `4718592`). -- **ISO 8601 Dates**: Dates MUST be stored as standard ISO strings (`YYYY-MM-DD` or ISO timestamp e.g. `"2026-02-14"`). -- **No Hardcoded UI Strings**: Do NOT store formatted strings like `"Rp 450 Juta"`, `"5.8 Miliar Ha"`, `"14 Jan 2026"` in domain interfaces or mock data fixtures. +- **Stack**: Solidity `^0.8.24`, Hardhat, Hyperledger Besu QBFT, OpenZeppelin Contracts. +- **Governance**: Follow [blockchain/AGENTS.md](blockchain/AGENTS.md). +- **Smart Contract Invariants**: + - Checks-Effects-Interactions (CEI) pattern is mandatory. + - Reentrancy protection: Use `ReentrancyGuard` on state-modifying payable/transfer functions. + - Role-based permissions: Use `AccessControl` (`onlyRole(DEFAULT_ADMIN_ROLE)`). + - No floating pragmas: Lock Solidity compiler version strictly. -### Centralized Presentation Formatters +### 4. Machine Learning & AI (`ml/`) + +- **Stack**: Python 3.12+, PyTorch / Scikit-learn, ONNX Runtime, Pydantic, Ruff. +- **Governance**: Follow [ml/AGENTS.md](ml/AGENTS.md). +- **ONNX Parity**: All exported ONNX audit models must achieve exact mathematical parity (`tolerance < 1e-5`) with PyTorch baselines. +- **Data Validation**: Model inference inputs and outputs must adhere strictly to Pydantic schemas. + +--- + +## 🤖 AI Agent Contribution Protocol + +Autonomous AI coding agents (Antigravity, Claude, Copilot, Cursor) collaborating on this codebase MUST follow these governance principles: + +1. **Read Governance First**: Before proposing or modifying code, agents MUST read root [AGENTS.md](./AGENTS.md) and the affected subproject's agent guide (`client/AGENTS.md`, `server/AGENTS.md`, `blockchain/AGENTS.md`, `ml/AGENTS.md`). +2. **Consult Monorepo Skills**: Agents must leverage the specialized skills located in `.agents/skills/`: + - [mock-repository-pattern](.agents/skills/mock-repository-pattern/SKILL.md) + - [data-formatting-standards](.agents/skills/data-formatting-standards/SKILL.md) + - [react-component-architecture](.agents/skills/react-component-architecture/SKILL.md) + - [shadcn](.agents/skills/shadcn/SKILL.md) + - [ui-ux-pro-max](.agents/skills/ui-ux-pro-max/SKILL.md) + - [design-md](.agents/skills/design-md/SKILL.md) + - [api-design-standards](.agents/skills/api-design-standards/SKILL.md) +3. **Mandatory Quality Gates**: Agents must execute local verification checks (`lint`, `typecheck`, `test`) on touched subprojects prior to claiming completion. +4. **Preserve Documentation Integrity**: Preserve comments, docstrings, and architectural invariants unless explicitly asked to modify them. +5. **Zero Secret Policy**: Agents must NEVER generate, hardcode, or log private keys, Besu keystores, passwords, or API tokens. + +--- + +## 🌿 Branch Naming Conventions + +All topic branches must use the following pattern: + +```text +// +``` + +| Type | Description | Example | +| :---------- | :----------------------------------------- | :------------------------------------ | +| `feat/` | New features or functional additions | `feat/client/carbon-wallet-modal` | +| `fix/` | Bug fixes and defect corrections | `fix/server/order-book-deadlock` | +| `refactor/` | Code refactoring without behavioral change | `refactor/blockchain/escrow-vault` | +| `perf/` | Performance optimizations | `perf/ml/onnx-feature-extractor` | +| `docs/` | Documentation, specs, and agent guides | `docs/contributing-guidelines-update` | +| `test/` | Adding or fixing test suites | `test/server/contract-envelope-specs` | +| `ci/` | GitHub Actions and developer tooling | `ci/pr-check-path-filter-tune` | + +**Allowed Scopes**: `client`, `server`, `blockchain`, `ml`, `contracts`, `db`, `infra`, `docs`. + +--- + +## 📝 Commit Message Guidelines + +We enforce the **Conventional Commits** standard. Keeping git history clean enables automated changelog generation and PR traceability. + +### Format + +```text +(): + +[optional body explaining motivation and changes] + +[optional footer(s), e.g. Closes #123 or BREAKING CHANGE: description] +``` + +### Types + +- **`feat`**: New feature +- **`fix`**: Bug fix +- **`refactor`**: Code restructuring without functional change +- **`perf`**: Performance improvement +- **`docs`**: Documentation only +- **`test`**: Tests added or corrected +- **`chore`**: Maintenance, dependencies, or tooling +- **`build`**: Build system or package changes +- **`ci`**: CI/CD pipeline or action scripts +- **`revert`**: Reverting a previous commit + +### Examples + +```text +feat(client): implement two-step confirmation modal for carbon retirement + +Closes #142 +``` + +```text +fix(server): prevent double debit race condition during order settlement +``` + +```text +test(blockchain): add reentrancy attack test cases for carbon DEX contract +``` + +--- + +## ✅ Quality Gates & PR Verification Matrix + +Every pull request to `main` is validated by automated CI checks ([.github/workflows/pr-check.yml](.github/workflows/pr-check.yml)). Verify the relevant checks locally before submitting: + +| Verification Category | Target Subproject | Local Command | +| :-------------------- | :------------------------ | :---------------------------------------------------------------------- | +| **Code Formatting** | Monorepo (Prettier) | `pnpm format:check` (or `pnpm format:write`) | +| **Python Formatting** | ML & Notifier (Ruff) | `pnpm ml:format:check` / `pnpm notifier:format:check` | +| **Static Typecheck** | Frontend Client | `pnpm client:typecheck` | +| | Backend Server | `pnpm server:typecheck` | +| | Smart Contracts | `pnpm blockchain:typecheck` | +| | Machine Learning | `pnpm ml:typecheck` | +| | Entire Monorepo | `pnpm typecheck` | +| **Linter Checks** | Frontend (Oxlint) | `pnpm client:lint` | +| | Backend (ESLint) | `pnpm server:lint` | +| | Python (Ruff) | `pnpm ml:lint` (or `pnpm py:lint`) | +| **Automated Tests** | Frontend (Vitest + Arch) | `pnpm client:test` | +| | Backend (Jest) | `pnpm server:test` | +| | Smart Contracts (Hardhat) | `pnpm blockchain:test` | +| | Machine Learning (Pytest) | `pnpm ml:test` | +| **API Contracts** | Client & Server Schemas | `pnpm test:contracts` | +| **Build Compilation** | Production Builds | `pnpm client:build` && `pnpm server:build` && `pnpm blockchain:compile` | + +--- -Formatting MUST occur dynamically at component rendering time using leaf utilities: +## 🔗 Additional Resources -| Format Category | Utility Function | Import Path | Output Example | -| :----------------- | :---------------------- | :----------------------------- | :------------------ | -| **IDR Currency** | `formatCurrency(val)` | `client/src/lib/formatters.ts` | `Rp 200.000.000` | -| **Carbon Tonnage** | `formatCarbon(val)` | `client/src/lib/formatters.ts` | `48.200 tCO2e` | -| **Land Area** | `formatArea(val)` | `client/src/lib/formatters.ts` | `2.450 ha` | -| **Percentage** | `formatPercent(val)` | `client/src/lib/formatters.ts` | `96,4%` | -| **File Size** | `formatFileSize(bytes)` | `client/src/lib/formatters.ts` | `4,5 MB` | -| **Date Display** | `formatDate(date)` | `client/src/lib/dates.ts` | `14 Feb 2026` | -| **Date & Time** | `formatDateTime(date)` | `client/src/lib/dates.ts` | `14/02/2026 14:32` | -| **Relative Time** | `formatLastSeen(date)` | `client/src/lib/dates.ts` | `5 menit yang lalu` | +- **Root Agent Governance**: [AGENTS.md](./AGENTS.md) +- **Frontend Agent Guide**: [client/AGENTS.md](client/AGENTS.md) & [client/DESIGN.md](client/DESIGN.md) +- **Backend Agent Guide**: [server/AGENTS.md](server/AGENTS.md) +- **Blockchain Agent Guide**: [blockchain/AGENTS.md](blockchain/AGENTS.md) +- **Machine Learning Agent Guide**: [ml/AGENTS.md](ml/AGENTS.md) +- **Security Policy**: [SECURITY.md](./SECURITY.md) +- **Pull Request Template**: [.github/pull_request_template.md](.github/pull_request_template.md)