Walle Design System

A production-ready scaffold that ships an Astro website, a DevContainer, GitHub Actions pipelines, and infrastructure stubs so you go from zero to deployed in minutes.

What is Walle

Walle is a copy-based design system for deploying web applications. It is not an npm package it is a full project scaffold distributed via a CLI that copies everything into your repository.

Each project gets four integrated layers out of the box:

  • Website Astro 6 with layouts, components, blog support, sitemap, RSS, and SEO defaults.
  • DevContainer Docker-based development environment with Node, OpenTofu, GitHub CLI, and pre-configured VS Code extensions.
  • CI/CD GitHub Actions workflows for testing (lint, build) and deploying to GitHub Pages, with reusable composite actions.
  • Infrastructure OpenTofu-ready directory for managing DNS, CDN, or any cloud resource alongside your site.

Customizations live in consumer zones. The @walle/ directories are read-only and replaced on update your code, config, and content are never touched.

How it works

  1. Init

    Run the CLI to scaffold a full project: website, DevContainer, CI/CD workflows, and infrastructure stubs ready to deploy.

  2. Configure

    Edit JSON configs for branding, navigation, and metadata. Override CSS variables for colors and fonts. Adjust the DevContainer and workflows to match your stack.

  3. Build

    Add pages, content collections, and custom components. Write your infrastructure with OpenTofu. The @walle/ directories stay read-only your code lives in consumer zones.

  4. Update

    When a new version ships, run `just walle-update`. Only @walle/ paths are replaced your content, config, and infra are untouched.

Quick start

Create a new project with everything included:

curl -fsSL https://raw.githubusercontent.com/FabrizioCafolla/walle-design-system/main/lib/scripts/@walle/cli.sh \
  | bash -s -- init --project-name my-site

Update @walle/ layers in an existing project:

just walle-update

Start developing locally inside the DevContainer:

just setup && just dev

Customization

Website config JSON files in src/configs/ control logo, navbar, footer, and app metadata.

CSS variables Override brand colors, spacing, and typography in src/styles/global.css.

Layout slots Replace navbar, footer, or inject extra <head> tags via named slots.

CI/CD & Infra Extend or override the provided GitHub Actions and OpenTofu modules without modifying @walle/ sources.