@anyblades/blades 3.0.0 → 3.1.0-alpha.2

package/README.md

@@ -4,9 +4,9 @@
 
 <!--section:summary-->
 
-<h1><b class="mark-brand">Minimal CSS Framework</b> <small>for</small> Semantic HTML</h1>
+<h1><span class="mark-brand">Minimal CSS Framework</span> <small>for</small> Semantic HTML</h1>
 
-<big>Fully compatible and actively maintained successor to [Pico CSS](//blades.ninja/css/pico/).</big>
+<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.
@@ -37,7 +37,7 @@ Simply switch `pico.css` to `blades.css` OR use `blades.standalone.css` with oth
 <link rel="stylesheet" href="css/blades.css" />
 ```
 
-### <mark>B.</mark> Usage from CDN
+### <mark>B.</mark> Usage from CDN <!--{#cdn}-->
 
 <!--prettier-ignore-->
 ```html
@@ -50,6 +50,8 @@ 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.
+
 ### <mark>C.</mark> Install with NPM
 
 ```sh
@@ -72,6 +74,44 @@ Alternatively, import [standalone](//blades.ninja/css/standalone/) Blades CSS so
 
 Live example using <i class="fa-brands fa-tailwind-css"></i> Tailwind: https://github.com/anyblades/buildawesome-micro-starters/blob/main/tailwind/styles.css
 
+<div><hr></div>
+
+Or import only the [Pico CSS](//blades.ninja/css/pico/) parts you need, e.g. per page or per component:
+
+```css
+@import "@anyblades/blades/pico/variables";
+@import "@anyblades/blades/pico/layout/document";
+@import "@anyblades/blades/pico/content/typography";
+@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`.
+- 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:
+
+```js
+// root layout, once
+import "@anyblades/blades/pico/variables";
+import "@anyblades/blades/pico/layout/document";
+
+// in the component that renders a <dialog>
+import "@anyblades/blades/pico/components/modal";
+```
+
+- 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.
+- 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.
+- Pico's landmark padding uses `body > header`, `body > main` and `body > footer`. These don't match when the framework wraps the page in an element: SvelteKit's `<div style="display: contents">`, Next.js pages router `#__next`, Nuxt `#__nuxt`, or a SPA's `#root` / `#app`. Next.js App Router doesn't wrap the page. If you rely on the padding, add it for your wrapper, e.g.:
+
+  ```css
+  #__next > :is(header, main, footer) {
+    padding-block: var(--pico-block-spacing-vertical);
+  }
+  ```
+
 ### <mark>D.</mark> Official starters
 
 - https://github.com/buildawesome-one/starter
@@ -109,6 +149,26 @@ Live example using <i class="fa-brands fa-tailwind-css"></i> Tailwind: https://g
 
 ---
 
+## 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.
+
+---
+
 ## Documentation
 
 <!-- ToC as is from https://blades.ninja/#docs -->
@@ -191,23 +251,30 @@ Live example using <i class="fa-brands fa-tailwind-css"></i> Tailwind: https://g
 ## <sup style>Trusted by</sup>
 
 - 🐍 [Flask & Jinja](https://palletsprojects.com/) community website
-- 🪐 [Grav CMS v2](https://getgrav.org/migrate-to-2#:~:text=blades) default theme
+- 🪐 [Grav CMS v2](https://getgrav.org/migrate-to-2#:~:text=blades) default theme [↗](https://www.followthatcar.com/)
+
+<!--https://pulsar-wildlife.club/-->
 
 <!--section:info-->
 
-## <sup style>Featured by</sup> <!-- Z-A after 11ty -->
+## <sup style>Featured by</sup> <!-- [1] big projects [2] awesome [3] smaller projects [4] blogs/social -->
 
 - [getgrav.org](https://getgrav.org/migrate-to-2#:~:text=blades)
 - [@11ty/buildawesome](https://bsky.app/profile/11ty.dev/post/3mp75r53ccv2b) [↗](https://mastodon.social/@11ty@neighborhood.11ty.dev/116816881367741413)
 - [<i class="fa-brands fa-build-awesome mark-brand"></i> buildawesome.one](https://buildawesome.one/#:~:text=blades)
-- [libhunt.com](https://www.libhunt.com/r/blades)
-- [context7.com](https://context7.com/anyblades/blades)
-- [awesome-css](https://github.com/uhub/awesome-css)
-- [awesome-css-frameworks](https://github.com/gabrielizalo/awesome-css-frameworks-and-ui-libraries/tree/master/Lightweight)
-- [@pauleveritt](https://fosstodon.org/@pauleveritt/116387278969347700)
-- [@daviding](https://www.reddit.com/r/Wordpress/comments/1vnfhkr/comment/p3k9z1c/#:~:text=blades)
+- https://github.com/dbohdan/classless-css
+- https://github.com/uhub/awesome-css
+- [/gabrielizalo/awesome-css-frameworks](https://github.com/gabrielizalo/awesome-css-frameworks-and-ui-libraries/tree/master/Lightweight)
+- 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)
+- [@draupnerdata](https://www.youtube.com/watch?v=yDjArj9HSjs&t=180s)
 - [@cantdutchthis](https://news.ycombinator.com/item?id=48729467)
-- [@adamdjbrett](https://github.com/adamdjbrett/11ty-wisp#features:~:text=blades)
+- [@daviding](https://www.reddit.com/r/Wordpress/comments/1vnfhkr/comment/p3k9z1c/#:~:text=blades)
+- [@infotexture](https://mastodon.social/@infotexture@indieweb.social/117294194740314396)
+- [@lazarus](https://fosstodon.org/@lazarus/117384358792615667)
+- [@matthewmorete](https://bsky.app/profile/matthewmorete.com/post/3mx5wvywixc2l)
+- [@pauleveritt](https://fosstodon.org/@pauleveritt/116387278969347700)
 
 <!--{.markerless .columns}-->
 <!--[hostfurl.com, @johnheenan]-->