Components

All @walle components are MANAGED — they live in src/@walle/components/ and are re-synced on every walle update. Customize through configs, CSS variables, slots, and the consumer’s own component layer.

API conventions

Every @walle component uses one shared prop vocabulary. If a component accepts one of these concepts, it uses exactly this name and type:

Rules:

• English only: source, comments, docs, and every user-facing or screen-reader-announced string ships an English default, overridable via props or config.app for localization.
• Boolean modifiers are positive and unprefixed: outline, centered, reversed, fullWidth, disabled.
• Polymorphic components (Button as <a> or <button>) decide from href presence — there is no as prop.
• Slots over content props whenever content is rich (cards, sections).
• The vocabulary applies to component props. Consumer config files (navbar.json, footer.json) keep their own schema (url, name, …) — they are a stable consumer-facing contract, not component APIs.

Config files

Four JSON files in src/configs/, all schema-validated (just validate-configs):

Component variants

Some components ship multiple visual variants. The active variant is selected per-component in src/configs/app.json under the components key:

{
  "components": {
    "navbar": "standard",
    "footer": "minimal"
  }
}

An absent key defaults to standard. An unknown variant name fails the build with an explicit error listing the available values.

Available variants

standard — the full-featured default (logo, navigation items, dropdowns for navbar; full link columns for footer).

minimal — stripped-down layout suitable for landing pages or apps where nav chrome would be distracting.

How variant selection works

Each component with variants has a resolver (*Resolver.astro) that reads config.app.components at build time and renders the correct variant file:

src/@walle/components/features/
  Navbar/
    Navbar.astro             ← standard variant
    Navbar.minimal.astro     ← minimal variant
    NavbarResolver.astro     ← reads config, renders the selected variant
  Footer.astro               ← standard variant
  Footer.minimal.astro       ← minimal variant
  FooterResolver.astro       ← reads config, renders the selected variant

BaseLayout imports the resolver, not the concrete component. The consumer never needs to change the layout import.

Adding a new variant

Variants are added in the walle source, not in consumers. If you are working on the walle design system itself:

1. Create Component.<variant>.astro next to the standard implementation.
2. Register the variant in AVAILABLE_VARIANTS in src/@walle/define-config.ts.
3. Add the variant to the component’s resolver (*Resolver.astro).

The resolver picks up the selection from config.app.components. The e2e scenario 11_component_variants.sh covers both the valid and invalid variant cases.

Overriding a component without forking

When the built-in variants don’t fit, replace the component entirely from a consumer-owned file rather than editing src/@walle/.

Example: replace the Navbar

---
// src/pages/index.astro
import BaseLayout from "@walle/layouts/BaseLayout.astro";
import MyNavbar from "@components/MyNavbar.astro";
---

<BaseLayout>
  <MyNavbar slot="navbar" />
  <!-- page content -->
</BaseLayout>

BaseLayout exposes navbar and footer slots for this purpose. Anything in those slots replaces the default @walle component entirely.

Elements

Primitive UI components. Import from @walle/components/elements/<Name>.astro.

Badge

Inline label with optional icon and link.

Link

Styled <a> with external-link detection: absolute URLs pointing at another host get rel="noopener noreferrer", target="_blank" and an external icon (disable with externalIcon={false}).

Image

Wrapper over astro:assets. An ImageMetadata import renders optimized with responsive srcset; a remote URL string renders a plain <img> and requires width/height (CLS prevention). alt is required (empty string only for decorative images).

Price

Locale-aware price via Intl.NumberFormat (locale defaults to the site language from config). compareAt renders struck-through with accessible original/discounted labels (English defaults, overridable).

Button

Renders an <a> styled as a button when href is set, a <button> otherwise.

Features

Higher-level components. Import from @walle/components/features/<Name>.astro or from the barrel @walle/components via index.js.

Navbar and Footer are exposed as their resolvers — import Navbar from @walle/components and you get variant selection automatically.

Navbar / Footer

See Variant selection above. Both read their config from the consumer’s src/configs/navbar.json and src/configs/footer.json; accept an explicit config prop to override.

Navbar slots: brand (replaces the logo area), actions (appended at the end of the nav, for CTA buttons).

Head

Renders all <head> meta tags. Used inside layouts — not imported directly in pages.

Section

Content section wrapper.

SectionFlow

Animated step list with scroll-triggered reveal.

interface FlowStep {
  number: number;
  title: string;
  description: string;
  icon?: string;
}

SectionHeaderStandard

Full-width page header with optional image and 3D tilt on hover.

CollectionFilters

Config-driven client-side filtering (text search + multi-select facets) over any rendered collection. Items carry data-filter-item plus one data-<key> attribute per facet (comma-separated values) and optional data-search; the component hides non-matching items and announces the visible count in a live region. With JavaScript disabled the filter UI stays hidden and every item remains visible. Replaces the former BlogFilters (used internally by BlogPostsLayout).

Blog components

Carousel

Native CSS scroll-snap carousel — no library, no autoplay, no infinite loop. Swipe is native scrolling; overlay prev/next buttons and slide position labels are the only JavaScript. Slides go in the default slot; each gets role="group" and an “i of N” label (template overridable via slideLabel). Reduced motion disables smooth scrolling. With zoom, image slides gain an expand affordance and open full screen in a native <dialog> lightbox (Esc/backdrop/close button to dismiss).

ProductCard

Renders a ProductData object (name, description, image, price with optional compareAt, availability, badge, href) — the same shape feeds Product JSON-LD. Availability is communicated as text, never color alone. Card boundary: has a price → ProductCard; no price → BasicCard.

SectionColumns

CSS-grid column section: columns caps the count on wide screens, auto-fit/minmax collapses to one column on narrow viewports — no JavaScript, no breakpoint props. Content goes in the default slot.

StructuredData

Renders schema.org JSON-LD from a plain object (or array); @context is added automatically. Builders for the common shapes live in @walle/utils/structured-data: websiteJsonLd, organizationJsonLd, articleJsonLd, productJsonLd. Layouts wire it automatically — AbstractLayout emits WebSite + Organization from config, BlogPostLayout emits Article, DetailLayout emits Product/Offer when given a product — so pages only add their own extra shapes.

Other features

Layouts

Import from @walle/layouts/<Name>.astro.

AbstractLayout

Base HTML wrapper. Loads Head, global.css, and Analytics. Renders a skip link as the first focusable element, targeting #main-content (provided by BaseLayout).

Props: headerTitle, headerDescription, headerImage, headerOgImage, headerRobots, headerLanguage, skipLinkLabel (default "Skip to content")

Slots: head (injected inside <head> after <Head />), default (body content)

BaseLayout

Extends AbstractLayout. Adds <Navbar> and <Footer>. Inherits all AbstractLayout props.

Slots: head (forwarded to AbstractLayout), navbar (replaces default <Navbar>), footer (replaces default <Footer>), default (page content inside <main>)

DetailLayout

Generic detail page: SectionHeaderStandard (title + badges slot) over a responsive two-column grid — default slot as main column, aside slot as sidebar — with optional backLink and breadcrumbs. Composes with ProductData content for product detail pages.

Props: title (required), description, ogImage, breadcrumbs (BreadcrumbItem[]), backLink ({ href, label? }, label defaults to "Back"), headerEffect

Slots: badges, default (main), aside

BlogPostLayout

Single blog post. Accepts post frontmatter via props and renders title, date, reading time.

BlogPostsLayout

Blog listing page. Accepts title, description, posts[].