docs: conform DESIGN.md to design.md spec

Reorder sections to canonical Overview/Colors/Typography/Layout/
Elevation & Depth/Shapes/Components/Do's and Don'ts, drop heading
numbers and the H1 title, add Layout and Shapes sections, and add
version: alpha. Regenerate public/llms*.txt.
This commit is contained in:
Tommaso Casaburi
2026-06-26 16:25:50 +07:00
parent 24e340e4b6
commit 802aa2a447
3 changed files with 69 additions and 17 deletions
+34 -8
View File
@@ -1,4 +1,5 @@
--- ---
version: alpha
name: 5chan name: 5chan
description: A decentralized imageboard with a classic imageboard user experience. description: A decentralized imageboard with a classic imageboard user experience.
colors: colors:
@@ -77,9 +78,7 @@ components:
rounded: "{rounded.square}" rounded: "{rounded.square}"
--- ---
# Design System: 5chan ## Overview
## 1. Overview
**Creative North Star: "The Preserved Imageboard"** **Creative North Star: "The Preserved Imageboard"**
@@ -96,7 +95,7 @@ Most surfaces are flat, compact, text-first, and visibly old web. Controls may l
- Text links and bracketed actions over large button components. - Text links and bracketed actions over large button components.
- Visual compatibility with classic imageboard user expectations. - Visual compatibility with classic imageboard user expectations.
## 2. Colors ## Colors
The palette is inherited from classic imageboard themes and should remain recognizable. Use the existing CSS variables in `src/themes.css` as the source of truth for implementation. The palette is inherited from classic imageboard themes and should remain recognizable. Use the existing CSS variables in `src/themes.css` as the source of truth for implementation.
@@ -131,7 +130,7 @@ The palette is inherited from classic imageboard themes and should remain recogn
**The Functional Color Exception.** Small, deterministic per-entity colors used as data — for example a hashed swatch that gives each connected peer a stable identity — are allowed. Render them as flat, square, small indicators (not gradients, glows, or large fills). This exception is for conveying data, not for decoration or branding. **The Functional Color Exception.** Small, deterministic per-entity colors used as data — for example a hashed swatch that gives each connected peer a stable identity — are allowed. Render them as flat, square, small indicators (not gradients, glows, or large fills). This exception is for conveying data, not for decoration or branding.
## 3. Typography ## Typography
**Display Font:** Tahoma, sans-serif. **Display Font:** Tahoma, sans-serif.
**Body Font:** Arial, Helvetica, sans-serif. **Body Font:** Arial, Helvetica, sans-serif.
@@ -152,7 +151,22 @@ The palette is inherited from classic imageboard themes and should remain recogn
**The Browser-Native Rule.** Do not add custom web fonts, variable-font display systems, negative letter spacing, oversized headings, or marketing typography to product surfaces. **The Browser-Native Rule.** Do not add custom web fonts, variable-font display systems, negative letter spacing, oversized headings, or marketing typography to product surfaces.
## 4. Elevation ## Layout
Layouts are dense, compact, and text-first, mirroring classic imageboard information density. Spacing is small and deliberate rather than generous, and structure comes from tables, inline rows, and slash-separated links instead of large spaced-out cards.
- **Page edge** (`5px`): outer gutters around boards, catalogs, and threads.
- **Field padding** (`2px`): inputs, table cells, and compact controls.
- **Compact padding** (`0.5em`): reply blocks, menus, and small panels.
- **Hairline** (`1px`): borders and separators between rows, posts, and panels.
Desktop and mobile intentionally differ: desktop stays maximally compact, while mobile raises tap-target and text sizes only as much as needed to stay usable and avoid browser zoom.
### Named Rules
**The Density Rule.** When in doubt, choose the more compact layout. Whitespace is not a feature on core imageboard surfaces.
## Elevation & Depth
5chan is flat by default. Depth is conveyed through background color, 1px borders, hard separators, and occasional legacy-style hard shadows on small menus. Avoid soft elevation, glass, blur, ambient shadows, floating cards, and layered dashboard surfaces. 5chan is flat by default. Depth is conveyed through background color, 1px borders, hard separators, and occasional legacy-style hard shadows on small menus. Avoid soft elevation, glass, blur, ambient shadows, floating cards, and layered dashboard surfaces.
@@ -164,7 +178,19 @@ The palette is inherited from classic imageboard themes and should remain recogn
**The Flat Surface Rule.** If a surface can be separated with a border or theme background, do that instead of adding shadow. **The Flat Surface Rule.** If a surface can be separated with a border or theme background, do that instead of adding shadow.
## 5. Components ## Shapes
5chan is uniformly square. Corner radius is `0` everywhere on product surfaces, and structure comes from 1px theme borders rather than rounding or elevation.
- **Corners:** square (`0` radius) on buttons, inputs, cards, replies, modals, and menus.
- **Borders:** 1px theme border colors (for example Yotsuba `#d9bfb7`, Yotsuba B `#b7c5d9`).
- **Indicators:** functional per-entity swatches render as small flat squares, never rounded chips.
### Named Rules
**The No Rounding Rule.** Do not introduce `border-radius`, pill, capsule, chip, or rounded badge shapes on product UI. A label is square text, not a rounded token.
## Components
### Buttons ### Buttons
@@ -208,7 +234,7 @@ The palette is inherited from classic imageboard themes and should remain recogn
- **Copy:** short labels and direct status messages. - **Copy:** short labels and direct status messages.
- **Behavior:** custom features such as challenges, settings, and posting flows should feel like imageboard utilities, not app dialogs. - **Behavior:** custom features such as challenges, settings, and posting flows should feel like imageboard utilities, not app dialogs.
## 6. Do's and Don'ts ## Do's and Don'ts
### Do ### Do
+34 -8
View File
@@ -504,6 +504,7 @@ Source: https://github.com/bitsocialnet/5chan/blob/master/DESIGN.md
```markdown ```markdown
--- ---
version: alpha
name: 5chan name: 5chan
description: A decentralized imageboard with a classic imageboard user experience. description: A decentralized imageboard with a classic imageboard user experience.
colors: colors:
@@ -582,9 +583,7 @@ components:
rounded: "{rounded.square}" rounded: "{rounded.square}"
--- ---
# Design System: 5chan ## Overview
## 1. Overview
**Creative North Star: "The Preserved Imageboard"** **Creative North Star: "The Preserved Imageboard"**
@@ -601,7 +600,7 @@ Most surfaces are flat, compact, text-first, and visibly old web. Controls may l
- Text links and bracketed actions over large button components. - Text links and bracketed actions over large button components.
- Visual compatibility with classic imageboard user expectations. - Visual compatibility with classic imageboard user expectations.
## 2. Colors ## Colors
The palette is inherited from classic imageboard themes and should remain recognizable. Use the existing CSS variables in `src/themes.css` as the source of truth for implementation. The palette is inherited from classic imageboard themes and should remain recognizable. Use the existing CSS variables in `src/themes.css` as the source of truth for implementation.
@@ -636,7 +635,7 @@ The palette is inherited from classic imageboard themes and should remain recogn
**The Functional Color Exception.** Small, deterministic per-entity colors used as data — for example a hashed swatch that gives each connected peer a stable identity — are allowed. Render them as flat, square, small indicators (not gradients, glows, or large fills). This exception is for conveying data, not for decoration or branding. **The Functional Color Exception.** Small, deterministic per-entity colors used as data — for example a hashed swatch that gives each connected peer a stable identity — are allowed. Render them as flat, square, small indicators (not gradients, glows, or large fills). This exception is for conveying data, not for decoration or branding.
## 3. Typography ## Typography
**Display Font:** Tahoma, sans-serif. **Display Font:** Tahoma, sans-serif.
**Body Font:** Arial, Helvetica, sans-serif. **Body Font:** Arial, Helvetica, sans-serif.
@@ -657,7 +656,22 @@ The palette is inherited from classic imageboard themes and should remain recogn
**The Browser-Native Rule.** Do not add custom web fonts, variable-font display systems, negative letter spacing, oversized headings, or marketing typography to product surfaces. **The Browser-Native Rule.** Do not add custom web fonts, variable-font display systems, negative letter spacing, oversized headings, or marketing typography to product surfaces.
## 4. Elevation ## Layout
Layouts are dense, compact, and text-first, mirroring classic imageboard information density. Spacing is small and deliberate rather than generous, and structure comes from tables, inline rows, and slash-separated links instead of large spaced-out cards.
- **Page edge** (`5px`): outer gutters around boards, catalogs, and threads.
- **Field padding** (`2px`): inputs, table cells, and compact controls.
- **Compact padding** (`0.5em`): reply blocks, menus, and small panels.
- **Hairline** (`1px`): borders and separators between rows, posts, and panels.
Desktop and mobile intentionally differ: desktop stays maximally compact, while mobile raises tap-target and text sizes only as much as needed to stay usable and avoid browser zoom.
### Named Rules
**The Density Rule.** When in doubt, choose the more compact layout. Whitespace is not a feature on core imageboard surfaces.
## Elevation & Depth
5chan is flat by default. Depth is conveyed through background color, 1px borders, hard separators, and occasional legacy-style hard shadows on small menus. Avoid soft elevation, glass, blur, ambient shadows, floating cards, and layered dashboard surfaces. 5chan is flat by default. Depth is conveyed through background color, 1px borders, hard separators, and occasional legacy-style hard shadows on small menus. Avoid soft elevation, glass, blur, ambient shadows, floating cards, and layered dashboard surfaces.
@@ -669,7 +683,19 @@ The palette is inherited from classic imageboard themes and should remain recogn
**The Flat Surface Rule.** If a surface can be separated with a border or theme background, do that instead of adding shadow. **The Flat Surface Rule.** If a surface can be separated with a border or theme background, do that instead of adding shadow.
## 5. Components ## Shapes
5chan is uniformly square. Corner radius is `0` everywhere on product surfaces, and structure comes from 1px theme borders rather than rounding or elevation.
- **Corners:** square (`0` radius) on buttons, inputs, cards, replies, modals, and menus.
- **Borders:** 1px theme border colors (for example Yotsuba `#d9bfb7`, Yotsuba B `#b7c5d9`).
- **Indicators:** functional per-entity swatches render as small flat squares, never rounded chips.
### Named Rules
**The No Rounding Rule.** Do not introduce `border-radius`, pill, capsule, chip, or rounded badge shapes on product UI. A label is square text, not a rounded token.
## Components
### Buttons ### Buttons
@@ -713,7 +739,7 @@ The palette is inherited from classic imageboard themes and should remain recogn
- **Copy:** short labels and direct status messages. - **Copy:** short labels and direct status messages.
- **Behavior:** custom features such as challenges, settings, and posting flows should feel like imageboard utilities, not app dialogs. - **Behavior:** custom features such as challenges, settings, and posting flows should feel like imageboard utilities, not app dialogs.
## 6. Do's and Don'ts ## Do's and Don'ts
### Do ### Do
+1 -1
View File
@@ -36,7 +36,7 @@ This file is generated by `scripts/generate-llms-files.mjs`. Do not hand-edit it
- [5chan](https://github.com/bitsocialnet/5chan/blob/master/README.md): 5chan is a serverless, adminless, decentralized and open-source imageboard built on the [Bitsocial protocol](https://bitsocial.net). It features the classic imageboard directory structure, but with a crucial differenc... - [5chan](https://github.com/bitsocialnet/5chan/blob/master/README.md): 5chan is a serverless, adminless, decentralized and open-source imageboard built on the [Bitsocial protocol](https://bitsocial.net). It features the classic imageboard directory structure, but with a crucial differenc...
- [AGENTS.md](https://github.com/bitsocialnet/5chan/blob/master/AGENTS.md): This file defines the always-on rules for AI agents working on 5chan. Use this as the default policy. Load linked playbooks only when their trigger condition applies. - [AGENTS.md](https://github.com/bitsocialnet/5chan/blob/master/AGENTS.md): This file defines the always-on rules for AI agents working on 5chan. Use this as the default policy. Load linked playbooks only when their trigger condition applies.
- [Product](https://github.com/bitsocialnet/5chan/blob/master/PRODUCT.md): product - [Product](https://github.com/bitsocialnet/5chan/blob/master/PRODUCT.md): product
- [Design System: 5chan](https://github.com/bitsocialnet/5chan/blob/master/DESIGN.md): **Creative North Star: "The Preserved Imageboard"** - [Overview](https://github.com/bitsocialnet/5chan/blob/master/DESIGN.md): **Creative North Star: "The Preserved Imageboard"**
- [src/AGENTS.md](https://github.com/bitsocialnet/5chan/blob/master/src/AGENTS.md): These rules apply to `src/**`. Follow the repo-root `AGENTS.md` first, then use this file for code inside the application source tree. - [src/AGENTS.md](https://github.com/bitsocialnet/5chan/blob/master/src/AGENTS.md): These rules apply to `src/**`. Follow the repo-root `AGENTS.md` first, then use this file for code inside the application source tree.
- [scripts/AGENTS.md](https://github.com/bitsocialnet/5chan/blob/master/scripts/AGENTS.md): These rules apply to `scripts/**`. Follow the repo-root `AGENTS.md` first, then use this file for automation and workflow helpers. - [scripts/AGENTS.md](https://github.com/bitsocialnet/5chan/blob/master/scripts/AGENTS.md): These rules apply to `scripts/**`. Follow the repo-root `AGENTS.md` first, then use this file for automation and workflow helpers.
- [Known Surprises](https://github.com/bitsocialnet/5chan/blob/master/docs/agent-playbooks/known-surprises.md): This file tracks repository-specific confusion points that caused agent mistakes. - [Known Surprises](https://github.com/bitsocialnet/5chan/blob/master/docs/agent-playbooks/known-surprises.md): This file tracks repository-specific confusion points that caused agent mistakes.