@anyblades/blades 3.1.0-alpha.1 → 3.1.0-beta.2

package/README.md

@@ -8,7 +8,6 @@
 
 <big>Fully compatible and actively maintained successor to [Pico CSS](https://picocss.com/).</big>
 
-Introduces [float labels](//blades.ninja/css/float-label/), [breakout container](//blades.ninja/css/breakout/) and other modern, opt-out [helpers](//blades.ninja/#docs).
 Simply switch `pico.css` to `blades.css` OR use `blades.standalone.css` with other frameworks.
 
 <nav>
@@ -50,7 +49,7 @@ Live example: https://github.com/pallets/website/blob/main/src/pallets/templates
 
 Full list of CSS files available on CDN: https://cdn.jsdelivr.net/npm/@anyblades/blades@3/css/
 
-`pico.layered.min.css` is Pico wrapped in `@layer pico { }`, so any unlayered styles of yours win over it without specificity fights. Note that inside a layer Pico's own `!important` declarations (form validation, reduced motion) beat your unlayered `!important`, and your `@keyframes` of the same name as Pico's win regardless of load order. When you can use `@import`, `@import url("…/pico.min.css") layer(pico);` does the same without this file.
+`blades.layered.min.css` is Blades wrapped in `@layer blades { }`, so any unlayered styles of yours win over it without specificity fights. Note that inside a layer Blades' own `!important` declarations (form validation, reduced motion) beat your unlayered `!important`, and your `@keyframes` of the same name as Blades' win regardless of load order. When you can use `@import`, `@import url("…/blades.min.css") layer(blades);` does the same without this file.
 
 ### <mark>C.</mark> Install with NPM
 
@@ -82,13 +81,47 @@ Or import only the [Pico CSS](//blades.ninja/css/pico/) parts you need, e.g. per
 @import "@anyblades/blades/pico/variables";
 @import "@anyblades/blades/pico/layout/document";
 @import "@anyblades/blades/pico/content/typography";
+@import "@anyblades/blades/pico/components/card";
 @import "@anyblades/blades/pico/components/modal";
 ```
 
 - `variables` and `layout/document` are the minimum; keep the same order as [`src/pico/_index.css`](https://github.com/anyblades/blades/blob/main/src/pico/_index.css) (variables → layout → content → forms → components → utilities).
-- Some parts build on others, e.g. `components/group` and `components/dropdown` expect `forms/basics` and `content/button`.
+- `layout` doesn't pad `body > header/main/footer`. Add `layout/landmarks` for Pico's behaviour.
+- Some parts build on others, e.g. `components/modal` expects `components/card`, and `components/group` and `components/dropdown` expect `forms/basics` and `content/button`.
 - Available parts are the files under [`src/pico/`](https://github.com/anyblades/blades/tree/main/src/pico): `layout/*`, `content/*`, `forms/*`, `components/*` (or a whole category, e.g. `@anyblades/blades/pico/components`) and `utilities`.
 
+#### With bundlers and component frameworks (SvelteKit, Next.js, Nuxt, Astro, …)
+
+Import the parts from JavaScript, i.e. the root layout and the components that use them, rather than with `@import` inside a component's `<style>` block. Use the layered parts, `@anyblades/blades/layered/*`: they are the same parts wrapped in `@layer blades`, which a JS `import` can't add by itself.
+
+```js
+// root layout, once: the base and every part that others build on
+import "@anyblades/blades/layered/variables";
+import "@anyblades/blades/layered/layout/document";
+import "@anyblades/blades/layered/content/typography";
+import "@anyblades/blades/layered/content/button";
+import "@anyblades/blades/layered/forms/basics";
+
+// in the component that renders a <dialog>
+import "@anyblades/blades/layered/components/card";
+import "@anyblades/blades/layered/components/modal";
+```
+
+```html
+<style>
+  /* unlayered, so it wins over Blades whatever the specificity (except Blades' !important) */
+  article {
+    max-width: 40rem;
+  }
+</style>
+```
+
+- Bundlers dedupe JS-side CSS imports and split them per route, so each part is downloaded and cached once and only where it's used.
+- Override in your component's `<style>` or `app.css`, or set `--pico-*` variables on `:root` or on an element. Unlayered CSS always wins over `@layer blades`. The usual layer caveats apply: Blades' own `!important` declarations beat yours, and if you use other layered CSS, declare the order once, before anything else is loaded. For Tailwind v4 that is `@layer theme, base, blades, components, utilities;` at the top of the CSS file you import first (before `@import "tailwindcss"`), and that file has to be imported before any `layered/*` part, because the first `@layer` the browser sees fixes the order.
+- Parts don't `@import` the parts they build on (e.g. `components/modal` expects `components/card`, `components/group` and `components/dropdown` expect `content/button` and `forms/basics`, and the `forms/*` extras expect `forms/basics`). If they did, every route chunk would carry its own copy. Import those shared parts once, at the root or next to the part that needs them; bundlers dedupe the imports.
+- An `@import` inside a scoped `<style>` (Svelte, Astro, Vue `scoped`) is processed as that component's own styles. The rules get scoped to the component's markup (Svelte also prunes the unused ones) and are duplicated in every component that imports them.
+- Landmark padding: `pico.css` and `blades.ninja.css` pad `body > header`, `body > main` and `body > footer` like Pico, which doesn't match when the framework wraps the page in an element (SvelteKit's `<div style="display: contents">`, Next.js pages router `#__next`, Nuxt `#__nuxt`, a SPA's `#root` / `#app`). `blades.css` doesn't pad them; with per-part imports, add `layout/landmarks` (or `layered/layout/landmarks`) for Pico's `body >` padding.
+
 ### <mark>D.</mark> Official starters
 
 - https://github.com/buildawesome-one/starter
@@ -126,6 +159,46 @@ Or import only the [Pico CSS](//blades.ninja/css/pico/) parts you need, e.g. per
 
 ---
 
+## Dark mode without a flash
+
+With the Pico-based builds, Blades follows the OS setting by default, with no JavaScript and no flash (see [Dark scheme](//blades.ninja/css/color-schemes/)). To force a theme, set `data-theme="light"` or `"dark"` on `<html>`. On a nested element it works when the element paints its own background, such as `<article>`; otherwise add `background-color: var(--pico-background-color); color: var(--pico-color);`.
+
+If you persist the user's choice, e.g. under the `localStorage` key `theme`, set the attribute **before the first paint** with a small inline script in `<head>`, e.g. in SvelteKit's `src/app.html`:
+
+```html
+<script>
+  try {
+    const theme = localStorage.getItem("theme");
+    if (theme === "light" || theme === "dark") document.documentElement.dataset.theme = theme;
+  } catch {}
+</script>
+```
+
+- Setting it later, e.g. in `onMount` or `useEffect`, renders the OS theme first and then switches.
+- In a Next.js App Router layout, pass the same code as a template literal, ``<script dangerouslySetInnerHTML={{ __html: `try { … } catch {}` }} />``, and add `suppressHydrationWarning` to `<html>`, because the attribute changes before hydration.
+
+---
+
+## Compact sizing (opt-in)
+
+Add `<html data-compact>` for the whole page, or put the attribute on a single element, e.g. `<form data-compact>` for one form. Without the attribute nothing changes.
+
+- **Where it ships:**
+  - included in `blades.css`
+  - also in `blades.layered.css`
+  - with per-part imports, add `@import "@anyblades/blades/compact";` after the other parts, or `import "@anyblades/blades/layered/compact";` with the layered parts
+  - with `pico.conditional.css`, add `@anyblades/blades/compact` after it
+- **What changes:**
+  - smaller control padding and 1.5rem block spacing
+  - a 0.5rem radius and a 3px focus ring
+  - 500-weight labels and buttons, 600-weight headings
+  - a white field background in light mode
+  - a 1px card ring instead of the blurred shadow, with no grey card header/footer bands
+- **Root font size:** on `<html>`, it also keeps the root font size at 100% instead of growing with the viewport. At 1280px wide, controls are then 38px instead of 62px. On a single element they are about 48px, because everything is sized in `rem` and the root stays as it is.
+- **Field text size:** form controls stay at 16px, because below that iOS Safari zooms in on focus.
+
+---
+
 ## Documentation
 
 <!-- ToC as is from https://blades.ninja/#docs -->
@@ -209,6 +282,7 @@ Or import only the [Pico CSS](//blades.ninja/css/pico/) parts you need, e.g. per
 
 - 🐍 [Flask & Jinja](https://palletsprojects.com/) community website
 - 🪐 [Grav CMS v2](https://getgrav.org/migrate-to-2#:~:text=blades) default theme [↗](https://www.followthatcar.com/)
+
 <!--https://pulsar-wildlife.club/-->
 
 <!--section:info-->
@@ -224,6 +298,7 @@ Or import only the [Pico CSS](//blades.ninja/css/pico/) parts you need, e.g. per
 - https://github.com/eggplantpasta/greenroom
 - [/adamdjbrett/11ty-wisp](https://github.com/adamdjbrett/11ty-wisp#features:~:text=blades) [↗](https://github.com/adamdjbrett/000000076#:~:text=blades)
 - [doany.io](https://doany.io/en/posts/svelte-bun-sqlite/#on-biome-and-css)
+- [@box464](https://mastodon.social/@box464/117442493473921346)
 - [@draupnerdata](https://www.youtube.com/watch?v=yDjArj9HSjs&t=180s)
 - [@cantdutchthis](https://news.ycombinator.com/item?id=48729467)
 - [@daviding](https://www.reddit.com/r/Wordpress/comments/1vnfhkr/comment/p3k9z1c/#:~:text=blades)