ForEveryone Berlin Design System

This is the shared look and feel for foreveryone.berlin, an open, inclusive community space in Berlin. It keeps the brand's colours, type, and reusable building blocks in one place, so everything we make looks like it belongs together. It is here for designers, developers, and anyone curious about how the brand fits together.

You can see it all in action on the live preview: design.foreveryone.berlin

For developers

Technical detail; non-developers can skip this.

Tech stack

• Tokens: W3C DTCG JSON (tokens/*.json) with $value, $type, $description.
• Build: Node script scripts/build-css.js generates css/custom-properties.css.
• CSS: Authored layers in css/*.css (variables only, no raw values).
• Prototype: Next.js 15 + TypeScript (App Router) in prototype/.
• Hosting: Vercel at design.foreveryone.berlin (legacy fe-design-system.vercel.app 301-redirects there).
• Production target: WordPress + Elementor Pro on foreveryone.berlin (global colors, global fonts, custom CSS).
• CI: GitHub Actions for token build + test + prototype build, and auto-release on v*.*.* tag.

Quick start

# Build CSS custom properties from tokens
node scripts/build-css.js

# Run the prototype locally
cd prototype && npm install && npm run dev
# → http://localhost:3000

Root package.json script aliases: npm run build, npm test, npm run prototype:dev, npm run prototype:build, npm run prototype:lint.

How tokens work

1. Token values live in tokens/*.json (W3C DTCG shape: $value, $type, $description).
2. scripts/build-css.js reads tokens/index.json imports.
3. The script generates css/custom-properties.css (the :root block). Do not hand-edit it.
4. Authored layers in css/*.css consume variables via var(--…).
5. The marketing site and the Next.js prototype both read from the same generated file.

scripts/build-css.test.js validates the DTCG shape and smoke-checks the generated CSS.

Repository layout

foreveryone-design-system/
├── tokens/          # Source-of-truth token JSON (DTCG)
├── css/             # Generated + authored CSS
├── scripts/         # Build, test, and PR helpers
├── prototype/       # Next.js preview app
├── elementor/       # Global colors / fonts / custom CSS for the marketing site
├── figma/           # Tokens Studio sync notes
├── docs/            # Guides, ADRs, agent contracts
│   ├── AGENTS.md    #   ↳ full docs index + domain rules
│   └── skills/      #   ↳ repeatable workflows (tokens, releases)
├── .cursor/         # Cursor agent (AGENTS.md + path-scoped rules)
├── .claude/         # Claude Code (rules + project skills)
├── AGENTS.md        # Repo-root mirror of docs/AGENTS.md
├── CLAUDE.md        # Claude Code session entry
└── CHANGELOG.md

Integrations

• Figma + Tokens Studio: figma/sync-guide.md and figma/token-export-instructions.md.
• Marketing site: Global colors elementor/global-colors.md, global fonts elementor/global-fonts.md, CSS setup elementor/custom-css-setup.md. Reference docs: docs/official-references.md.
• Visual styles (icons, blobs, photography, category icon set): docs/visual-styles.md.
• Logo usage (X measurement, safe zone, min sizes, white-on-orange exception): docs/logo-usage.md.
• Color audit (2026 brand-guide alignment + approved bg ⇄ text combinations): docs/color-audit-2026.md.
• Brand source of truth (authority matrix; Brand Book v1.0 governs): docs/brand-book-references.md.
• For AI agents (consume the system / redesign an app): llms.txt, spec/ (machine-readable tokens, principles, component contracts), and docs/agents/redesign-from-this-system.md.

Git workflow

• main is the default branch (protected, release-ready). develop is the integration branch.
• Branch from develop using feature/*, fix/*, docs/*, chore/*.
• Use Conventional Commits.
• PRs use .github/PULL_REQUEST_TEMPLATE.md.
• Solo flow: bash scripts/pr-and-merge.sh pushes the current branch, opens a PR, and merges it.
• Tag main with vX.Y.Z at release; see docs/skills/release.md.

AI coding assistants

• Canonical context: docs/AGENTS.md (full documentation index + domain rules).
• Repo-root mirror: AGENTS.md for tools that only auto-load root-level AGENTS.md (including Cursor CLI).
• Cursor IDE: .cursor/AGENTS.md + path-scoped rules in .cursor/rules/.
• Cursor CLI: AGENTS.md + CLAUDE.md + .cursor/rules/ (does not read .cursor/AGENTS.md).
• Claude Code: CLAUDE.md + path-scoped rules in .claude/rules/.
• Project skills (both tools): .claude/skills/ (ship-release, optimize-prototype); Cursor auto-loads from this folder.
• Agent contract + runtime policy: docs/agents/.
• Repeatable workflows: docs/skills/.

Contributing

See docs/contributing.md for workflow, commit conventions, and PR expectations.

Acknowledgements

This design system is a community effort. Built with care by the people who make ForEveryone Berlin what it is: a warm, open space where everyone belongs.

With thanks to Rie, Roxana, Didem, Pedram, Marco, and Angelina.

License

Dual-licensed in a single LICENSE file:

• Software (scripts/, prototype/): MIT.
• Design system (tokens/, css/, figma/, elementor/, docs/, agent docs, .claude/ and .cursor/ rules): CC BY-NC 4.0 (summary).

Changelog

Full history in CHANGELOG.md. GitHub Releases for each tag mirror the changelog entry.