DEV Community: FSCSS tutorial

Styling Deeply Nested divs with One FSCSS Array Loop (No More Hand-Writing Selectors)

FSCSS tutorial — Fri, 11 Sep 2026 17:08:54 +0000

Writing nested selectors by hand is painful.

div { background: orange; }
div div { background: purple; }
div div div { background: indigo; }
/* …and it gets worse the deeper you go */

FSCSS gives us a clean way to generate the entire chain in a single loop using @arr + rpt().

The Problem

You have a simple nested structure:

<div>1
  <div>2
    <div>3</div>
  </div>
</div>

You want each level to have a different background color (and maybe padding, border-radius, etc.) without writing the selectors manually.

The One-Loop Solution

<script src="https://cdn.jsdelivr.net/npm/fscss@1.2.0/runtime.min.js" async></script>

<style>
@arr colors[orange, purple, indigo]
@arr levels[count(3, 1)]          /* → 1, 2, 3 */

rpt(@arr.levels[], "div ") {      /* builds "div ", "div div ", "div div div " */
  background: @arr.colors[@arr.levels[]];
  padding: 10px;
  border-radius: 10px;
  color: #fff;
  margin: 8px;
}
</style>

That’s it.

What Gets Generated

div {
  background: orange;
  padding: 10px;
  border-radius: 10px;
  color: #fff;
  margin: 8px;
}

div div {
  background: purple;
  /* same properties */
}

div div div {
  background: indigo;
  /* same properties */
}

How It Works

@arr levels[count(3, 1)] creates the numbers 1, 2, 3.
rpt(@arr.levels[], "div ") repeats the string "div " according to the current level.
Inside the rule, @arr.colors[@arr.levels[]] picks the matching color (arrays are 1-indexed).
FSCSS expands the whole block once for every item in the array — one clean loop.

Easy Variations

Change depth

Just update the count() and the colors array:

@arr colors[tomato, coral, salmon, crimson]
@arr levels[count(4, 1)]

Use child combinator instead of descendant

rpt(@arr.levels[], "div > ") {
  /* now generates div >, div > div >, etc. */
}

Add more properties or even different values per level

You can reference the level index for anything — font-size, opacity, animation-delay, etc.

Why This Feels Good

Zero repetitive typing
Depth and colors stay in sync
Still pure CSS after compilation
Works with the browser runtime or the CLI

Hand-writing nested selectors used to be a small but annoying chore. With FSCSS arrays + rpt(), it becomes a one-liner pattern you can reuse anytime.

Full: https://fscss.devtem.org/nested-loop

Building a Lightweight Portfolio Dashboard with ProvChart & st-core Tokens

FSCSS tutorial — Fri, 11 Sep 2026 15:49:34 +0000

Open-source template: github.com/Figsh/dashboard-project

Most dashboard tutorials start the same way: pull in 40–150 KB of JavaScript, wait for hydration, and hope search engines eventually see the chart.

We wanted the opposite.

This is a dark portfolio dashboard that:

Renders charts with zero charting JavaScript on the page
Uses ProvChart to turn data into pure HTML + CSS
Keeps the original st-core.fscss design tokens for a consistent, high-end look
Stays crawlable, fast on first paint, and easy to theme

This article walks through how it was built and how you can reuse the template.

The problem with typical chart libraries

Approach	Cost	First paint	SEO / crawl
JS Libs	40–150 KB+ JS	After hydration	Often missed
Hand-written CSS charts	Fragile, limited points	Instant	Good
ProvChart	0 KB chart runtime	Instant	Excellent

ProvChart compiles your data into CSS custom properties and returns scoped HTML + CSS. The browser paints the shape with native CSS (clip-path, gradients, etc.). No chart library ships to the client.

Stack overview

ProvChart API — POST /api/v1/generate → { html, css }
st-core tokens — the same CSS variables used by st-core.fscss
Vite — fast local dev and simple build
Tiny Node proxy — keeps the API key off the browser

Design tokens stay exactly as they were:

:root {
  --st-bg:       #080710;
  --st-surface:  #0f0e1c;
  --st-card:     #13122a;
  --st-accent:   #6c47ff;
  --st-accent-2: #a78bff;
  --st-green:    #00e5a0;
  --st-red:      #ff4d6a;
  --st-text:     #edeaff;
  --st-muted:    #5e5a82;
  --st-border:   rgba(108, 71, 255, 0.13);
}

The UI (sidebar, KPIs, allocation bars, activity feed, profile dropdown) is pure CSS on top of these tokens. Charts are the only part that talks to an external service.

How ProvChart is wired in

1. Server-side proxy (key stays private)

// api/proxy-server.js (simplified)
const res = await fetch('https://provchart-api.devtem.org/api/v1/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.PROVCHART_API_KEY,
  },
  body: JSON.stringify(payload),
});

The browser only calls /api/chart. Never expose a live key in frontend bundles.

2. Client payload (real numbers, not 0–100)

{
  type: 'area',
  theme: 'midnight',
  height: 260,
  axisX: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun', 'Mon', 'Now'],
  series: [
    { name: 'Portfolio', color: '#6c47ff', points: [74200, 76800, …, 84201] },
    { name: 'Benchmark', color: '#00c9b8', points: [72800, 74500, …, 81000] },
  ],
  legend: true,
  grid: true,
}

ProvChart auto-formats large values (20K, 1.3K, 2M, 1.09B…). You send raw numbers; you do not pre-format with k / M / B.

3. Inject HTML + CSS

const { html, css } = await res.json();
host.innerHTML = html;
// each chart gets its own <style> so instances never clobber each other

Each host (#main-chart-host, #spark-btc-host, …) keeps a scoped style tag. That avoids the classic “last chart wins and the others go blank” bug.

Data shape: 9 points, clear narrative

Instead of 24 noisy points, every series uses 9 points with a deliberate arc:

Downfall — a clear dip
High rate — a strong recovery into “Now”

Example (1W portfolio):

portfolio: [74200, 76800, 75500, 72800, 71500, 76200, 79800, 82500, 84201]
//          Mon     Tue    Wed    Thu    Fri    Sat    Sun    Mon    Now
//                         ↘ dip ─────────↗ strong climb

Labels stay short and aligned (Mon … Now). No client-side slicing or thinning.

Dashboard features in the template

Period tabs: 1D / 1W / 1M / 3M / 1Y (each re-requests ProvChart)
KPI row + overview stats strip
Main multi-series area chart (Portfolio vs Benchmark)
BTC / ETH spark area charts
Allocation bars + recent activity feed
Sidebar with profile dropdown
Live clock, responsive layout, same st-core visual language

Everything is vanilla JS modules + CSS. No React/Vue required.

Getting started

git clone https://github.com/Figsh/dashboard-project.git
cd dashboard-project
npm install

cp .env.example .env
# or export PROVCHART_API_KEY="your_api_key"
# add PROVCHART_API_KEY from https://chart.devtem.org/dashboard

# Terminal 1 — proxy
npm run proxy

# Terminal 2 — Vite
npm run dev

Open http://localhost:5173.

Free tier note: ProvChart free accounts get a small number of generations per month.

Why this approach works

First paint — charts appear with the CSS; no wait for a chart library.
Bundle size — zero charting JS on the page.
Crawlability — the chart structure is real HTML.
Theme control — st-core tokens + ProvChart theme: "midnight" keep the look consistent.
Security — API key only lives on the proxy / edge function.

You still get dynamic period switching and multi-series visuals; you just don’t pay the usual JavaScript tax.

Repo & next steps

Template: github.com/Figsh/dashboard-project
ProvChart: chart.devtem.org
st-core.fscss: underlying token/chart primitives used by the design system

Fork it, swap the datasets, point the proxy at your own backend, or pre-generate SVGs with the ProvChart GitHub Action for static docs.

Lightweight dashboards don’t have to look lightweight. With ProvChart and a solid token set, they can look like a product — and still load like a static page.

FSCSS Array Loops: Generating Repeated CSS Rules with @arr

FSCSS tutorial — Tue, 08 Sep 2026 15:00:09 +0000

One of the most useful tools in FSCSS for cutting down repetitive CSS is the array system. Arrays let you store ordered lists of values and expand them into repeated rules automatically, instead of writing five or six nearly identical blocks by hand.

This post walks through how @arr works, how the loop trigger behaves, and the pattern used in real FSCSS modules like siri-wave.fscss.

Declaring Arrays

Arrays in FSCSS are 1-indexed and string-native. The first item is [1], not [0].

@arr colors[magenta, cyan, green, purple, orange, blue]
@arr delays[0.1s, 0.25s, 0.45s, 0.15s, 0.35s, 0.55s]
@arr indexes[count(6,1)]   /* generates 1,2,3,4,5,6 */

count(n, start) is the standard way to generate a numeric index array. You can also declare literal lists of any CSS value type: colors, sizes, times, strings.

Accessing Individual Items

background: @arr.colors[1];      /* magenta */
animation-delay: @arr.delays[3]; /* 0.45s */

The Loop Trigger: Empty Brackets

The core feature is the empty bracket syntax, @arr.name[].

When FSCSS sees @arr.name[] inside a selector that's followed by a block, it expands the rule once for every item in the array.

@arr delays[0.1s, 0.3s, 0.5s]
@arr colors[#ef4444, #f59e0b, #10b981]
@arr indexes[count(3,1)]

.loading-dot:nth-child(@arr.indexes[]) {
  animation-delay: @arr.delays[@arr.indexes[]];
  background: @arr.colors[@arr.indexes[]];
}

This compiles to:

.loading-dot:nth-child(1) {
  animation-delay: 0.1s;
  background: #ef4444;
}
.loading-dot:nth-child(2) {
  animation-delay: 0.3s;
  background: #f59e0b;
}
.loading-dot:nth-child(3) {
  animation-delay: 0.5s;
  background: #10b981;
}

A Real Example: siri-wave.fscss

Here's the pattern as it's actually used in siri-wave.fscss:

@define siri-blob-colors(st:.blob){`
  @arr siri-colors[magenta, cyan, green, purple, orange, blue]
  @arr siri-colors-i[count(6,1)] 

  @siri-blob-variant(@use(st).@arr.siri-colors[@arr.siri-colors-i[]], @arr.siri-colors[@arr.siri-colors-i[]])

  @use(st){
    /* Need a block to trigger the loop */
    --siri-loop-index: @arr.siri-colors-i[];
  }
`}

Breaking down what happens:

Two parallel arrays are declared: one for values, one for indexes.
The empty [] sits inside a selector/argument that's followed by a block.
FSCSS expands the whole statement six times, once per index.
Each expansion calls @siri-blob-variant with the matching color name, producing .blob.magenta, .blob.cyan, and so on.

This index-array-plus-parallel-values pattern is the recommended way to generate multiple variants cleanly, without writing each variant out by hand.

Rules for Reliable Looping

@arr.name[] must appear in a selector position followed by a { } block. A bare reference inside a mixin argument alone won't trigger the loop reliably.
Prefer an explicit index array (count(n,1)) whenever you need to index into other arrays.
Arrays are expanded entirely at compile time. The output is plain CSS, with no runtime array logic left behind.

Array Methods

Method	What it does	Example
`.length`	Number of items	`@arr.colors!.length`
`.first` / `.last`	First / last item	`@arr.colors!.first`
`.list`	Comma-separated list	`@arr.colors!.list`
`.join(sep)`	Join with custom separator	`@arr.colors!.join(+)`
`.reverse`	Reversed list	`@arr.colors!.reverse`
`.shuffle`	Random order	`@arr.colors!.shuffle`
`.indices`	1-based index list	`@arr.colors!.indices`
`.randint`	One random value for the compile	`@arr.colors!.randint`

Short list

The Mental Model

Think of @arr.name[] as "for each item in this array, generate a rule." That's the entire mechanism behind the six colored blobs in siri-wave, generated without writing six almost-identical blocks by hand.

FSCSS isn't just a different syntax for writing CSS. It's growing into an ecosystem of reusable libraries, tools, and resources meant to make modern web development faster and less repetitive.

The siri-wave repo: siri-wave.fscss on GitHub

st-core.fscss: a chart and dashboard UI kit built entirely in CSS mixins

FSCSS tutorial — Sat, 05 Sep 2026 23:19:55 +0000

Most chart libraries hand you a JavaScript API and a bundle size to worry about. st-core.fscss takes a different route: it's a set of FSCSS mixins that compile straight to CSS, no JavaScript required to render a chart, a stat card, or a progress bar.

It's open source, and the whole thing lives in one readable source file.

What it can do right now

st-core.fscss covers the pieces you'd actually reach for on a dashboard or analytics screen:

Line and area charts, drawn with clip-path: polygon() against eight data points
Data dots placed along the line, generated automatically from an array so you don't write eight separate rules by hand
A background grid and axis labels, sized to match your data
Stat cards, with label, value, and an up/down delta built in
Progress bars, driven by a single custom property so the fill can be updated later without touching the markup
A device-frame container, if you want the whole thing to look like it's sitting inside a phone mockup

Everything reads from one shared design-token set, colors, radii, spacing, chart defaults, so a single st-root() call at the top of your stylesheet themes the whole kit.

Why it's built this way

Every piece is a plain @define mixin. Call st-chart-points(68, 59, 70, 35, 58, 22, 42, 55) with your real numbers, call st-chart-line() and st-chart-fill(), and you have a working chart, no chart.js, no canvas, no re-render logic. Update the data later by calling st-chart-points() again with new numbers, and every dot, line, and fill shifts to match.

That's the appeal for a dev workflow: you're writing CSS-shaped code the whole time. Nothing to import beyond FSCSS itself, nothing to configure beyond the parameters you pass.

Syntax highlighting

If @define, @use(), and @arr look unfamiliar in an editor with no idea what FSCSS is, the FSCSS VS Code extension fixes that. It adds proper syntax highlighting and snippets for FSCSS files, so reading or writing st-core.fscss mixins looks like reading CSS, not a wall of unhighlighted text. Worth installing before you open the source for the first time.

Where to start

The repo itself is short enough to read start to finish in one sitting, and there's a companion explainer walking through what every mixin does and why, mixin by mixin, if you'd rather understand the mechanics before you start calling them. Both beginners picking up FSCSS for the first time and developers who already know the compiler should be able to get a chart on screen within a few minutes either way.

Repo: github.com/fscss-ttr/st-core.fscss

FSCSS v1.2.0 is out: two clean entry points, full backward compatibility, and inline styles that actually compile

FSCSS tutorial — Fri, 04 Sep 2026 23:55:28 +0000

FSCSS is open source, built in the open, and free for anyone to use, extend, or pick apart. That's the whole point of it. Every release is meant to make it easier for other developers to build with, not harder. v1.2.0 is the clearest example of that yet.

What shipped

Previous versions of FSCSS scattered their browser-facing files across the package: /e/exec.js, /exec.js, /xfscss.js, /xfscss.min.js, and more. Depending on what you needed, you'd end up guessing which file was the right one to load.

v1.2.0 consolidates all of that into two public entry points:

<!-- Auto-run, for plain HTML pages -->
<script src="https://cdn.jsdelivr.net/npm/fscss@1.2.0/runtime.min.js" async></script>

// Manual control, for tooling and modules
import xfscss from "https://cdn.jsdelivr.net/npm/fscss@1.2.0/esm.js";

runtime.js auto-scans the page and compiles everything on load, <style> blocks, <link type="fscss"> sources, and now inline style attributes too. esm.js never auto-runs and never touches page loading, since it's meant for using FSCSS as a tool: an FSCSS-to-CSS converter, a build step, or any pipeline where you decide what gets processed and when.

Use one or the other. Never both.

Nothing breaks

This is the part worth repeating: the npm package and CLI are completely unchanged, and every method that worked in the 1.1.x line still works exactly the same way in 1.2.0. @define, @fun, @event, @arr, pattern(), all of it. The consolidation only touches the browser entry-point files. If you're compiling ahead of time with the CLI, this release changes nothing for you.

Inline styles now go through the full pipeline

This is the headline feature. From v1.2.0, style="..." attributes are compiled on boot the same way <style> blocks are:

<style>
  @define btn-style(bg: #636EE7){
    padding: 10px 20px;
    color: color-mix(#dddddd, @use(bg));
    background: @use(bg);
    border: 2px solid;
    border-radius: 25px;
    font-weight: 700;
  }
</style>

<button style="@btn-style(#1a2a4f)">Search</button>
<button style="@btn-style(#f00f00)">Search</button>

Combined with xfscss.process(), that means an inline mixin call can be recompiled at runtime and swapped straight back into the element, no rewritten CSS, no framework state:

const update = async (btn) => {
  const newStyle = await xfscss.process("@btn-style(@arr.colors!.randint)");
  btn.setAttribute("style", newStyle);
};

The full walkthrough of this: including a detail (method declared inline stay resolvable even after their declaration is cleaned out of the attribute), if you want to go deeper: FSCSS v1.2.0 lets you write mixins directly in style="...".

Why this matters for an open-source tool

None of this is about adding complexity for its own sake. FSCSS exists to cut down on repetitive CSS and give developers capabilities plain CSS doesn't have natively, and every release should make that easier to reach for, not harder to keep up with. Two entry points instead of a pile of internal files. Full compatibility instead of a migration guide. A feature that makes the JS API and the language work together instead of sitting side by side.

Open source only stays useful if the people using it can trust an upgrade won't cost them a rewrite. That's the bar this release was held to.

Get it

npm install fscss@latest

<script src="https://cdn.jsdelivr.net/npm/fscss@1.2.0/runtime.min.js" async></script>

Bug reports, feature requests, and pull requests are all welcome on GitHub

FSCSS Component Architecture: A Modular, Composition-First Approach to CSS

FSCSS tutorial — Thu, 03 Sep 2026 15:58:02 +0000

FSCSS component architecture is built around a modular, composition-first model that compiles to plain CSS. It emphasizes reusable style units, design tokens, conditional logic, and selective imports—with almost no runtime JavaScript required for the final output. Components in FSCSS are treated as pure style definitions rather than framework-specific widgets, keeping stylesheets readable, highly reusable, and free of classic “mega-stylesheet” problems while still producing standard CSS that any browser understands.

Core Building Blocks

FSCSS provides a focused set of primitives for defining and composing styles:

Primitive	Purpose	Best for	Introduced / Key version
`str(name, "…")`	Named blocks of CSS declarations	Simple reusable style snippets	Core
`@fun(name){…}`	Key-value stores (design tokens)	Spacing scales, color palettes, property groups	Core
`@define name(params)`	Parameterized mixins	Themed components, variants, full structures	1.1.15+
`pattern(threshold: "desc", "…")`	Semantic / fuzzy matching	Natural-language style injection	1.1.25+
`@event name(param)`	Conditional value functions	Themes, states, calculations	Core
`@arr(name[…])`	Arrays + iteration	Generated classes, loops, scales	Core
`@import`	Selective / wildcard module loading	Modular architecture & ecosystem modules	Core

How Components Are Structured

1. Atomic / Token Layer (@fun + variables)

Design tokens sit at the foundation so every component draws from a single source of truth:

@fun(tokens) {
  primary: #2563eb;
  radius-md: 8px;
  space-4: 1rem;
  shadow-sm: 0 1px 3px rgba(0,0,0,.1);
}

2. Base Style Blocks (str() or @fun full-block)

Related declarations are grouped into reusable blocks that can be dropped into any selector:

str(card-base, "
  padding: @fun.tokens.space-4.value;
  border-radius: @fun.tokens.radius-md.value;
  box-shadow: @fun.tokens.shadow-sm.value;
  background: white;
")

3. Parameterized Components (@define)

True mixins accept arguments and can be composed freely:

@define button(bg: #2563eb, fg: white, pad: 0.75rem 1.5rem) {
  background: @use(bg);
  color: @use(fg);
  padding: @use(pad);
  border: none;
  border-radius: @fun.tokens.radius-md.value;
  cursor: pointer;
}

@define button-hover(bg) {`
  &:hover { background: @use(bg); }
`}

.btn-primary {
  @button()
  @button-hover(#1d4ed8)
}

4. Semantic / Intent-based Styles (pattern())

Styles can be described in plain language; FSCSS matches by similarity:

pattern(0.6: "elevated card with soft shadow", `
  border-radius: 12px;
  padding: 1.5rem;
  box-shadow: 0 10px 25px rgba(0,0,0,.08);
  background: white;
`)

.product-card {
  elevated card with soft shadow
}

5. Conditional & Dynamic Behavior (@event + @arr)

Themes, states, and generated variants are handled at compile time without external logic:

@event theme(mode) {
  if mode: dark { return: #0f172a; }
  el { return: #f8fafc; }
}

body {
  background: @event.theme(dark);
}

Modular Architecture & Ecosystem

FSCSS encourages splitting styles into focused modules and importing only what is needed:

@import((page-root, page-hero) from customizable)
@import((*) from form)
@import((st-chart-line, st-stat-card) from st-core)

Modules that follow this pattern:

st-core — pure-CSS charts & stat cards (data via CSS custom properties)
form — floating labels, checkboxes, switches, validation (checkbox-hack style)
circle-progress — progress rings with color logic driven by @event + @arr
customizable — page shells (nav, hero, CTA, footer, typography)
cube — pure CSS 3D cube faces with micro-effects

Each module is self-contained, token-driven, and designed so multiple modules can coexist on one page without conflicts.

Recommended Project Layout

styles/
  tokens.fscss          ← @fun + $variables
  components/
    button.fscss        ← @define + str()
    card.fscss
    form.fscss
  layouts/
    page.fscss
  main.fscss            ← selective @imports + composition

Compile with the CLI for production (fscss main.fscss dist/styles.css) so the shipped CSS has zero runtime dependency.

Key Design Principles

Composition over inheritance — stack small @defines and str() blocks.
Tokens first — everything reads from @fun or $variables.
Selective imports — pull only the mixins a page needs.
Compile-time resolution — almost all logic runs at build time and disappears from the final CSS.
Progressive enhancement — start with simple str() / @fun, then graduate to @define and pattern() as complexity grows.

This architecture keeps stylesheets readable, highly reusable, and free of the classic “mega-stylesheet” problems while still producing standard CSS that any browser understands.

How pattern() Feels a Few Weeks In

FSCSS tutorial — Tue, 01 Sep 2026 15:06:19 +0000

I've written three posts now about pattern(): what it is, why it might matter for beginners and AI-generated CSS, and a demo module built on top of it. This one is different. It's less a tutorial and more a check-in, and a reason to keep teaching this in the open rather than writing it once and moving on.

The part that surprised me

I expected questions about syntax. I got questions about the matching itself instead. One reader asked directly how two patterns avoid matching the same phrase. Another pointed at the ambiguity tradeoff as the thing worth watching as the idea scales. Neither question was about how to write pattern(). Both were about whether it holds up.

That's the right question to be asking, and it's not fully answered yet. I know it holds up in a small module. I don't know yet how it holds up in a library with hundreds of patterns written by more than one person. That's genuinely still open, and I'd rather say that plainly than pretend the demo module settles it.

A short recap, for anyone catching up

If this is the first post of the series you've landed on:

pattern() lets you describe a piece of CSS in plain English instead of calling it by an exact name.

pattern(0.6: "rounded primary button", `
  border: none;
  border-radius: 8px;
  padding: 10px 20px;
  background: #764ba2;
  color: white;
`)

.btn {
  rounded primary button
}

The phrase inside .btn doesn't need to match the description exactly. It needs to score above the threshold, 0.6 here, on word similarity. Write something close enough, and it resolves. Write something unrelated, and it falls through as harmless literal text instead of breaking your build.

The earlier posts go deeper: the mechanics of pattern(), why this matters for beginners and AI-generated CSS, and patterns.fscss, a small open module you can fork.

What I'd tell a beginner trying this for the first time

Don't start by writing ten patterns. Start by writing one, for something you personally rewrite often, a card style, a button variant, whatever shows up in your own projects repeatedly. Give it a description in the words you'd actually use out loud. Then try triggering it with a slightly different phrase than the one you wrote, not the exact words, something close. If it matches, you've felt the whole idea in about two minutes. If it doesn't, lower the threshold slightly and try again. That's the entire learning curve.

The mistake to avoid is writing two patterns that are almost the same idea in almost the same words. I made this mistake myself in the first draft of patterns.fscss, two button patterns worded closely enough that matching between them was genuinely unclear. It's an easy trap, and the only real fix is noticing it and rewording, not a cleverer algorithm.

Where this goes next

I don't have a roadmap to announce. What I have is an open module and an open question about how well description-based matching holds up at scale. If you try pattern() on something real, whether it works cleanly or breaks in an interesting way, I'd rather hear about the break. That's more useful to the next person reading this series than another polished example would be.

Repo: github.com/fscss-ttr/patterns.fscss

Docs: fscss.devtem.org/pattern

Extension visualstudio

Generate pure CSS charts from Claude (or any MCP client)

FSCSS tutorial — Mon, 31 Aug 2026 08:18:10 +0000

Ask an agent for a chart today and it'll usually hand you a Chart.js config, or some SVG with hand-typed coordinates. Fine to look at in a chat window, but the moment you actually want it somewhere real, a README, a docs page, a landing page, you're back to pasting code into a sandbox, while the real UI still needed JS libs (or a screenshot).

So ProvChart now has an MCP server: the agent calls a tool and gets back real HTML/CSS or SVG, not a sketch of one.

Package

Tools

Tool	Output
`provchart_generate`	`html` + `css`
`provchart_generate_svg`	`svg` + `dataUri`
`provchart_explain`	short notes (no API call)

Paint doesn't need a client chart runtime. The optional provchart-runtime only adds hover/tooltips on HTML charts, nothing required for the chart to just render.

Claude Desktop

{
  "mcpServers": {
    "provchart": {
      "command": "npx",
      "args": ["-y", "provchart-mcp"],
      "env": {
        "PROVCHART_API_KEY": "pc_live_xxxxxxxx"
      }
    }
  }
}

Key from chart.devtem.org/dashboard.

Prompt that works

Monthly signups: Jan 120, Feb 450, Mar 3200, Apr 8900. SVG for the README.

Values can be real numbers, not squeezed onto a 0–100 scale. Optional min / max if you want a fixed axis instead of auto-scaling.

After the tool returns

HTML: inject css into a <style> tag, html into a container.

SVG: write it to a file and use ![alt](./charts/name.svg) in Markdown. Better than a huge data URI sitting in your README source.

Related automation

If you want charts without chatting to an agent for each one:

provchart-readme-action — JSON config → SVG in CI
provchart-repo-stats — stars / languages → SVG for the README, pulled straight from GitHub's API

Site: chart.devtem.org · Docs: chart.devtem.org/docs

I got tired of static README badges, so I made my repo stats real charts

FSCSS tutorial — Sun, 30 Aug 2026 17:18:57 +0000

Every README I've ever maintained has had that one section near the top: badges for stars, forks may be build status icon. They work, but they're just... images. Static, generic, the same little badge everyone else's repo has too.

What I actually wanted was simpler to describe than it turned out to be to build: pull the real numbers from a repo, turn them into an actual chart, commit it as an SVG, embed it like any other image. No third-party badge service holding my stats hostage, no client-side JS running in a README that can't run JS anyway.

So I built ProvChart Repo Stats.

What it actually writes

It's a GitHub Action. Point it at a repo, give it an API key, and on schedule (or on demand) it writes two SVGs straight into your repo:

File	Content	Default chart
`docs/charts/repo-overview.svg`	Stars, forks, watchers, open issues	area
`docs/charts/languages.svg`	Language share	horizontal bar

That's it. No hand-maintained JSON describing what the chart should look like, no dashboard to babysit. The numbers come from GitHub's API, the chart comes from ProvChart, the action wires the two together and commits the result.

Setup

1. Add a repo secret. Grab an API key from the ProvChart dashboard and save it as PROVCHART_API_KEY under your repo's Settings → Secrets → Actions.

2. Drop in the workflow.

name: Repo stats charts

on:
  schedule:
    - cron: "0 8 * * 0"
  workflow_dispatch:

permissions:
  contents: write

jobs:
  charts:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: fscss-ttr/provchart-repo-stats@v1.3
        with:
          api-key: ${{ secrets.PROVCHART_API_KEY }}
        env:
          PROVCHART_API_KEY: ${{ secrets.PROVCHART_API_KEY }}

      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "chore: update repo stats charts"
          file_pattern: "docs/charts/*.svg"

3. Embed the SVGs in your README like any other image.

![Overview](./docs/charts/repo-overview.svg)
![Languages](./docs/charts/languages.svg)

Run the workflow once manually, or just wait for the Sunday morning cron. The action commits the SVGs, your README stays plain Markdown, nothing else changes about how your repo works.

What the charts actually look like

The overview chart is an area chart plotting your real counts, not squeezed onto a 0-to-100 scale:

And the language breakdown renders as a clean horizontal bar, share by percentage:

A couple of defaults worth knowing

Overview uses real counts. If your repo has 3,200 stars, the chart says 3,200, it's not forced into a 0-100 box.
Languages render as share percentages, which is usually the more useful way to look at a language breakdown anyway.
Both are configurable if the defaults don't fit: overview-type and languages-type let you switch to bars if that's more your style.

Under the hood it's all generated through ProvChart's generate-svg endpoint, so there's no image hosting involved and nothing rendered client-side. The SVG is just... a file in your repo, same as any other asset.

If you already maintain a .provchart/charts.json and want fixed sample charts instead of live repo metrics, there's a sibling action for that: provchart-readme-action.

Try it

Repo, issues, and feedback: github.com/fscss-ttr/provchart-repo-stats

If you end up using it on something, I'd genuinely like to see what your README looks like with it. And if something breaks or a default doesn't make sense for your use case, open an issue, I'm actively maintaining this one.

fscss-ttr / provchart-repo-stats

Generate ProvChart SVG charts from GitHub repo stats (stars, forks, watchers, issues, languages)

ProvChart Repo Stats

GitHub Action that reads live repo health from the GitHub API and writes ProvChart SVG charts for your README.

v1.3 defaults

Chart	File	Type	Values
Overview	`docs/charts/repo-overview.svg`	area	Real stars, forks, watchers, open issues
Languages	`docs/charts/languages.svg`	hbar	Language share %

No hand-written chart JSON for basic stats — only a workflow and an API key.

Quick start

1. Secret

Repo Settings → Secrets and variables → Actions

Name	Value
`PROVCHART_API_KEY`	Key from chart.devtem.org/dashboard

2. Workflow

.github/workflows/repo-stats.yml:

name: Repo stats charts
on:
  schedule:
    - cron: "0 8 * * 0"
  workflow_dispatch:

permissions:
  contents: write

jobs:
  charts:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check secret
        env:
          KEY: ${{ secrets.PROVCHART_API_KEY }}
        run: |
          if [ -z "$KEY" ]; then
            echo "::error::PROVCHART_API_KEY is empty"
            exit 1
          fi
          echo "Secret OK

…

View on GitHub

Keep README charts in sync with a small GitHub Action

FSCSS tutorial — Fri, 28 Aug 2026 13:32:25 +0000

I got tired of updating chart screenshots in READMEs by hand.

Either the numbers were stale, or I’d regenerate an image, commit it, and forget the next week. For docs and GitHub READMEs I don’t need a full chart library on the page — I need a vector file that still looks sharp.

So I wired ProvChart’s SVG API into a GitHub Action.

What it does

You describe charts in .provchart/charts.json
On schedule or workflow_dispatch, the Action calls the API
It writes .svg files into the repo (e.g. docs/charts/)
A commit step pushes them if anything changed

README stays simple:

![API traffic](./docs/charts/demo.svg)

No Chart.js in the README. No screenshot pipeline.

Minimal setup

Secret: PROVCHART_API_KEY (from the ProvChart dashboard)

Config (array of payloads):

[
  {
    "file": "demo.svg",
    "type": "area",
    "theme": "midnight",
    "width": 640,
    "height": 320,
    "axisX": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
    "series": [
      {
        "name": "Requests",
        "color": "#8b7bff",
        "points": [20, 85, 40, 60, 10, 40, 95]
      }
    ]
  }
]

Workflow sketch:

- uses: fscss-ttr/provchart-readme-action@v1.0.4
  with:
    api-key: ${{ secrets.PROVCHART_API_KEY }}
    config: .provchart/charts.json
    output-dir: docs/charts

Then auto-commit the docs/charts/*.svg files if you want.

Why this shape

SVG fits Markdown and docs better than a heavy client chart stack
CI owns refresh; the README only references files
Same JSON model as the rest of ProvChart (line, area, bar, gauge, …)

Gauges at about 220×220 work well in a README without taking over the page.

Try without starting from zero

Sample repo (fork → add the secret → run the workflow):

github.com/Figsh/provchart-charts

Action:

github.com/fscss-ttr/provchart-readme-action

Not a replacement for interactive dashboards. Just a practical way to keep docs charts honest without babysitting PNGs.

fscss-ttr / provchart-readme-action

CI generates SVG charts and commits them for README/docs

ProvChart README Action

Generate vector SVG charts with the ProvChart API inside GitHub Actions, then commit them for live README and docs embeds.

No Chart.js. No screenshot bots. Pure SVG from JSON.

Action	`fscss-ttr/provchart-readme-action`
Sample repo (fork & test)	Figsh/provchart-charts
API	chart.devtem.org
License	MIT

Try in 2 minutes (recommended)

Fork github.com/Figsh/provchart-charts
Add a repository secret: PROVCHART_API_KEY (Dashboard → Developer API)
Actions → run Test ProvChart Action (workflow_dispatch)
SVGs land under docs/charts/ and are committed automatically

That repo already has .provchart/charts.json, the workflow, and README embeds.

Quick start (your own repo)

1. API key secret

Settings → Secrets and variables → Actions → New repository secret

Name	Value
`PROVCHART_API_KEY`	Your ProvChart API key

2. Config — `.provchart/charts.json`

[
  {
    "file": "demo.svg"
    "type": "area",
    "theme": "midnight",
    "width": 640,
    "height": 320,
    "axisX": [

…

View on GitHub

From st-core.fscss to ProvChart: Same CSS-Paint Idea, Built for Real Data

FSCSS tutorial — Wed, 26 Aug 2026 15:56:32 +0000

st-core.fscss started as an FSCSS module with a clear bet: charts can be browser paint, not a JavaScript chart runtime. No canvas. No SVG dependency for the line. Data lives in CSS custom properties; shapes are clip-path: polygon(); optional JS only writes numbers. Compiled, it’s on the order of ~0.5 kb of CSS—not a 40–150 kb chart library.

That idea spread—writeups, demos, dashboard experiments—because it matched what performance-minded frontends already wanted: first paint is the chart, crawlers see markup, updates can be variable writes with free CSS transitions.

ProvChart is not a rejection of that model. It’s what you build when the same philosophy has to survive arbitrary series lengths, multi-series layouts, and a server-side compile step—without asking every team to hand-author mixins per dataset.

What st-core actually nailed

st-core’s contract is intentionally tight and easy to teach:

Eight points: --st-p1 … --st-p8
Fixed X stops: 0% 14% 28% 42% 57% 71% 85% 100%
Mixins like @st-chart-points, @st-chart-line, @st-chart-fill, dots, stats
Optional JS: element.style.setProperty('--st-p3', '42%') → browser repaints the polygon

.chart {
  position: relative;
  height: 200px;
  /* FSCSS: @st-chart-points(20, 35, 33, 30, 48, 35, 66, 37) */
}

That is still a strong starter library for hand-built cards, marketing strips, and demos where eight samples are enough. It maximizes what the browser already does well. Nothing about ProvChart throws that away.

Where a fixed eight-point contract stops fitting

Real product data rarely arrives as “exactly eight numbers”:

Days in a month, weeks in a year, irregular sensor samples
Several series on one frame (revenue vs cost, traffic vs signups)
Automation: JSON from an API, not a mixin edited in a stylesheet

st-core’s elegance is that compile-time contract. ProvChart’s job is to keep data → variables → CSS geometry → paint when the point count and series count are decided per request, not per mixin signature.

What ProvChart changes (and what it doesn’t)

	st-core.fscss	ProvChart
Paint model	CSS variables + `clip-path` / native CSS	Same family of ideas
Point count	Eight fixed slots	Length of `series[].points` (no eight-slot ceiling)
Series	Hand composition / multi-line patterns in FSCSS	First-class multi-series, combo, bar, hbar, gauge, …
Authoring	Mixins in source / FSCSS compile	JSON → builder or Developer API
Client chart library	None	None for paint
Docs embeds	Manual / CSS	Optional `generate-svg`
Interaction	Hand dots / `attr()` patterns	Optional provchart-runtime

Unchanged belief: the chart is CSS. JavaScript should not be required to draw the shape.

Changed machinery: compilation can run on a server; geometry is generated for the payload you sent; roots are instance-scoped (classes like pc-… and variables such as --pc-{id}-s{series}-p{index}) so many charts can share a page without colliding.

There is no marketed “must be ≤ 200 points” product rule in this writeup. Practical limits are the usual ones: payload size, CSS complexity, and what stays smooth in real browsers—not an eight-argument mixin.

Server compile instead of only a `<style>` mixin

st-core path: FSCSS CLI or in-browser compile → you ship CSS you authored.

ProvChart path: send JSON, get markup:

const res = await fetch("https://provchart-api.devtem.org/api/v1/generate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.PROVCHART_API_KEY,
  },
  body: JSON.stringify({
    type: "line",
    series: [
      { name: "Revenue", color: "#8b7bff", points: [20, 35, 45, 30, 50] },
    ],
    axisX: ["Jan", "Feb", "Mar", "Apr", "May"],
  }),
});

const data = await res.json();
// data.html + data.css → inject; first paint is the chart

Five points or fifty—it’s the same call shape. For README and Markdown surfaces, POST /api/v1/generate-svg returns SVG / data URI without requiring a chart runtime on the doc page.

provchart-runtime: interaction without owning paint

st-core already showed the interaction seed: a dot, a tooltip, data on the element, CSS doing the rest.

provchart-runtime (MIT, npm provchart-runtime) generalizes that for generated HTML charts:

Finds [data-provchart]
Skips pure SVG exports when configured
Scroll reveal, legend focus, per-point tooltips (reading generated custom properties where present)
MutationObserver for charts injected after load

<script>
  window.ProvChartRuntimeConfig = {
    tooltips: true,
    perPointTooltips: true,
    observe: true,
    excludeSvg: true,
  };
</script>
<script
  src="https://cdn.jsdelivr.net/npm/provchart-runtime@1.0.0/dist/provchart-runtime.min.js"
  defer
></script>

Additive on purpose: generate output does not depend on the runtime; the runtime does not replace the engine.

The stack, honestly drawn

st-core.fscss (open source, viral pure-CSS chart idea)
  --st-p1…p8 · fixed X-stops · mixins · ~0.5kb compiled CSS
  JS optional: write variables, CSS transitions animate polygons
        │
        ▼
ProvChart (chart.devtem.org)
  Same paint philosophy · variable-length series · multi-series types
  Builder + Developer API → static HTML/CSS (and SVG for docs)
        │
        ▼
provchart-runtime (optional)
  Tooltips / motion / legend UX on HTML charts only

Open core: github.com/fscss-ttr/st-core.fscss
Product: chart.devtem.org
Runtime: github.com/fscss-ttr/provchart-runtime

When to use which

Use st-core when…	Use ProvChart when…
You want full control in FSCSS/CSS source	Data is JSON from backends, CI, or agents
Eight points (or st-core’s patterns) fit the story	Series length and count change per view
You’re deep in the FSCSS module ecosystem	You want API keys, quotas, SVG export, dashboard builder
Maximum clarity for teaching pure CSS charts	Production multi-series, combo, gauge, automation

Many teams will use both: st-core for crafted marketing cards; ProvChart when the dataset refuses to stay eight samples long.

st-core.fscss proved a viral, high-performance idea—browser-native paint, minimal JS, no chart-library tax. ProvChart keeps that idea and removes the fixed-slot ceiling so the same belief works when the numbers come from a database, not a mixin call.

ProvChart Follow

Charts that load with the first paint and stay crawlable ProvChart generates pure HTML + CSS charts from your data

Pure CSS Charts + Drop-in Interactivity: ProvChart API & Runtime

FSCSS tutorial — Tue, 25 Aug 2026 16:34:50 +0000

Most chart libraries tax every page: 40–150 KB of JS, hydration delay, and markup crawlers never see. ProvChart takes another path—data becomes HTML and CSS (custom properties + clip-path). ProvChart Runtime is an optional script that adds tooltips, motion, and legend focus without changing how charts are generated.

This post walks through a minimal setup: generate an area chart from the API, inject it, and let the runtime enhance it.

What you get

Layer	Role
ProvChart API	`POST /api/v1/generate` → `{ html, css }` — zero chart-library runtime on the page
ProvChart Runtime	Scans `[data-provchart]`, adds hover tooltips, scroll reveal, legend dimming
SVG API (optional)	`POST /api/v1/generate-svg` for README/docs — runtime skips pure SVG by design

Repo / install:

github.com/fscss-ttr/provchart-runtime
npm i provchart-runtime
CDN: jsDelivr or unpkg

Product: chart.devtem.org

1. Get an API key

Sign in at chart.devtem.org
Open Dashboard → Developer API
Create a key

Signed-up free accounts get a monthly test quota. HTML and SVG generations share the same pool.

2. Minimal page

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>ProvChart + Runtime</title>
  <style>
    body {
      margin: 0;
      min-height: 100vh;
      display: flex;
      align-items: center;
      justify-content: center;
      background: #0c0a16;
      font-family: system-ui, sans-serif;
    }
    #chart { width: min(640px, 92vw); }
    .err { color: #ff5e7d; font-size: 14px; padding: 16px; }
  </style>

  <script>
    window.ProvChartRuntimeConfig = {
      animation: true,
      revealOnScroll: true,
      tooltips: true,
      perPointTooltips: true,
      observe: true,
      selector: '[data-provchart]',
      excludeSvg: true,
    };
  </script>
  <script src="https://cdn.jsdelivr.net/npm/provchart-runtime@1.0.0/dist/provchart-runtime.min.js"></script>
</head>
<body>
  <div id="chart"></div>

  <script type="module">
    const API = 'https://provchart-api.devtem.org/api/v1/generate';
    const API_KEY = 'YOUR_API_KEY';

    const payload = {
      type: 'area',
      series: [
        { name: 'Traffic', color: '#4fd8c4', points: [30, 45, 40, 60, 55, 70, 65] },
        { name: 'Signups', color: '#f0a860', points: [8, 12, 11, 18, 16, 22, 20] },
      ],
      axisX: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
    };

    const mount = document.getElementById('chart');

    try {
      const res = await fetch(API, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-API-Key': API_KEY,
        },
        body: JSON.stringify(payload),
      });
      const data = await res.json();
      if (!data.success) throw new Error(data.error || 'Generate failed');

      let style = document.getElementById('provchart-style');
      if (!style) {
        style = document.createElement('style');
        style.id = 'provchart-style';
        document.head.appendChild(style);
      }
      style.textContent = data.css || '';
      mount.innerHTML = data.html || '';

      // Optional: only if your build exposes it
      // window.ProvChartRuntime?.scan?.();
    } catch (err) {
      mount.innerHTML = `<p class="err">${err.message}</p>`;
    }
  </script>
</body>
</html>

Replace YOUR_API_KEY. After load you should see a two-series area chart; hover legend/points if the runtime attached correctly.

3. How the runtime finds charts

Generated roots look like:

<div class="pc-chart-…" data-provchart="area">…</div>

The runtime:

Queries [data-provchart]
Skips pure SVG embeds when excludeSvg: true
Uses a MutationObserver so charts injected via fetch still get enhanced
Reads series points from CSS variables like --pc-{id}-s1-p1 for per-point tooltips

You don’t call into ProvChart’s core from the client for paint—the browser already painted CSS.

4. Config worth knowing

window.ProvChartRuntimeConfig = {
  animation: true,
  revealOnScroll: true,
  tooltips: true,
  perPointTooltips: true,
  countUp: true,      // gauge / stat numbers
  observe: true,      // watch DOM for new charts
  excludeSvg: true,   // leave README SVGs alone
};

Define this before the runtime script tag.

5. HTML/CSS vs SVG

Use case	Endpoint	Runtime
App UI, dashboard, marketing page	`/api/v1/generate`	Yes
GitHub README, static docs asset	`/api/v1/generate-svg`	No (commit `.svg` or data URI)

Same payload shape (type, series, axisX); different output.

6. Why this split matters

Performance: no Chart.js-sized dependency to parse before first paint
SEO: chart structure is in HTML/CSS on first response
Progressive enhancement: runtime is optional; charts work without it
Docs vs apps: SVG for Markdown hosts; HTML/CSS + runtime for product UI

Links

generate charts as HTML and CSS, ship them with almost no client chart code, and add interactivity only when you want it—with a single script tag