rastrillo / fiesta Public

Download this file

1	# Fiesta
2
3	Fiesta is a HTML/CSS component library and baseline design system: one stylesheet, a handful of optional scripts, and an example page for every component state. It began as Rastrillo's `ui/` and is now a package of its own, so a page on any stack can link it. Link one file and your markup is styled:
4
5	```html
6	<link rel="stylesheet" href="https://fiesta.rastrillo.org/1/fiesta.css">
7	```
8
9	That file is `tokens.css` and the Day theme joined, comments stripped, under 25 KiB gzipped. The tokens hold every component's layout and behaviour; the theme paints them. The markup for each component is under `examples/`, one page per state, and every page works on its own.
10
11	## Themes
12
13	Three themes ship, each as one file: `fiesta.css` is Day, the default; `fiesta-plain.css` is greyscale, system type and almost no shape; `fiesta-signal.css` is graphite and one cobalt. Use Day unless you have a reason not to.
14
15	The two-file form is the same CSS split in two: link `tokens.css`, then `day.css`, `plain.css` or `signal.css`. Take it when you serve your own copy and want to change theme without re-serving the tokens, or when you are writing a theme of your own. A page that uses the sidebar or console shell links `shell.css` as well; nothing else needs it.
16
17	```html
18	<link rel="stylesheet" href="https://fiesta.rastrillo.org/1/tokens.css">
19	<link rel="stylesheet" href="https://fiesta.rastrillo.org/1/signal.css">
20	```
21
22	## Scripts
23
24	Everything works with scripts off. The scripts are enhancements, each its own file and its own `<script>` tag, so you load the ones your page uses and nothing else. In load order:
25
26	- `fiesta.js` closes menus on an outside click and on Escape, lets a switch's knob be dragged, gives iOS its pressed state, and runs the colour-scheme menu. Load it first.
27	- `busy.js` shows a spinner on a submitted button and refuses a second submit.
28	- `light.js` lights the page from where the sun is at this hour and puts the pointer's position on the button under it. Delete it and the page is the still design.
29	- `anchor.js` keeps a dropdown's menu on the screen in a browser without CSS anchor positioning.
30	- `shell.js` is phone navigation for the sidebar and console shells.
31	- `transition.js` prevents an error when the browser skips a page transition on a column, stage or topbar page. Load it before the stylesheets, without `defer`, the one exception to the order above. Sidebar and console pages don't need it, because `shell.js` does the same.
32	- `copy.js` makes a snippet's Copy button copy its code, and keeps the button hidden where the browser has no clipboard.
33	- `select.js` makes a `<select data-rst-select>` searchable.
34	- `datetime.js` is the natural-language date field: "tomorrow", "next fri 9am", "in 2 weeks".
35	- `calendar.js` is the month grid `datetime.js` opens. Load it last.
36
37	```html
38	<script defer src="https://fiesta.rastrillo.org/1/fiesta.js"></script>
39	<script defer src="https://fiesta.rastrillo.org/1/select.js"></script>
40	```
41
42	## The colour scheme
43
44	The themes read `data-theme` on `<html>`: `light`, `dark`, or absent, which means System, the operating system's own setting. The scheme menu (`examples/scheme-menu/`) is three small forms, one per choice, and who remembers the choice is for the page to say.
45
46	If a server renders the page, it owns the scheme: it writes `data-theme` from a cookie or a profile, and the forms post to it. With `fiesta.js` loaded the change applies in place as well, and the form dispatches an `rst-scheme` event (it bubbles; `detail.scheme` is `light`, `dark` or `system`) that your own script can write the cookie from.
47
48	A page with no server behind it says so on `<html>` with `data-rst-scheme-store="local"`. Then `fiesta.js` keeps the choice in `localStorage` under `fiesta-scheme`, and applies it before first paint when the script is in `<head>` without `defer`. Without `fiesta.js` the switch has nothing to apply or remember, and the page follows System.
49
50	## Strings
51
52	`select.js`, `datetime.js` and `copy.js` put a few words on screen: "No matches", "Type to filter", the calendar's button labels, "Copied", and the vocabulary the date parser understands. They ship in twelve languages as `i18n/<lang>.json`, keyed by the `data-rst-` attribute each string answers to, with the prefix removed. Load `i18n/<lang>.js` beside the scripts and they read the table that matches your page's `lang`; an attribute on the element wins over the table, and English is the fallback written into the script. The JSON is there for your own build to read; a browser cannot fetch it from the CDN, which sends no CORS headers.
53
54	```html
55	<script defer src="https://fiesta.rastrillo.org/1/i18n/ga.js"></script>
56	```
57
58	The languages are Arabic, Bengali, English, Spanish, Irish, Hindi, Japanese, European Portuguese, Russian, Vietnamese, Cantonese and Simplified Chinese: `ar`, `bn`, `en`, `es`, `ga`, `hi`, `ja`, `pt-PT`, `ru`, `vi`, `yue` and `zh-Hans`.
59
60	## Icons
61
62	The icons are Lucide's, a few renamed, as inline SVG: paste the `<svg>` from `icons/<slug>.svg` beside its visible label. The release also carries `icons.svg`, a sprite with one `<symbol id="rst-icon-<slug>">` per icon, for `<use href="/icons.svg#rst-icon-check">`. A browser only draws a sprite from its own origin, so the sprite is for a site that serves its own copy of Fiesta. From the CDN, inline the SVG.
63
64	## Versions
65
66	Every release lives at its exact version, `https://fiesta.rastrillo.org/1.0.0/`, and those files never change. `/1/` is rewritten to the newest 1.y.z, so a page that links `/1/fiesta.css` picks up fixes without an edit; a change that would break existing markup is a new major, and `/2/` would be its own path. Link `/1/` unless you need bytes that never move, in which case pin the exact version. The same files are under `releases/<version>/` in this repository, with a `SHA256SUMS`.
67
68	## Browsers
69
70	The CSS needs Chrome 123, Safari 17.5, Firefox 121 or newer, because every theme colour is a `light-dark()`. Anything that shipped at or below that floor is used freely, `oklch()` and `color-mix()` included, with no fallback; an older browser gets an unstyled page. The policy is a rolling one: a feature is fair game about a year after it reached all three engines, and the floor is re-derived from the CSS when one is taken.
71
72	## The repository
73
74	`go get amadan.net/rastrillo/fiesta` gives a Go program the same files: `fiesta.FS()` is the whole tree to mount, `fiesta.TokensCSS()`, `ThemeCSS(name)`, `Script(name)`, `Strings(lang)` and `Icon(slug)` are its pieces, and the `example` package reads the examples. Neither package links a browser; the checks under `check/` do.
75
76	`make ci` is the whole gate; run it before you push. `DESIGN.md` says what the system is and why, and `hack/seed/README.md` says where the files came from. A release is `go run ./cmd/fiesta release -version X.Y.Z`, committed under `releases/`, and `make site` assembles the site into `.build/site/public`, which is the tree that ships. Fiesta is MPL-2.0; the icons carry Lucide's ISC notice.
77