css-is-awesome 1.1.0

package/scss/recipes/_bare-tags.scss

@@ -0,0 +1,232 @@
+// ============================================================================
+// BARE-TAG STYLING — Optional Pico-style drop-in
+// ============================================================================
+// Default behaviour of css-is-awesome is to leave bare HTML alone. Tokens,
+// utilities, mixins, and React components ship — bare <button>, <table>, <h1>
+// stay browser-default until the consumer styles them.
+//
+// This recipe styles the most common bare tags using existing mixins. It is
+// OPT-IN. If you want it, add this line ONCE in your app's SCSS entry:
+//
+//   @use 'css-is-awesome/scss/recipes/bare-tags';
+//
+// Or copy the contents into your own SCSS and edit to taste.
+//
+// Specificity is zero ( :where() = 0,0,0 ). To override, write ANY selector —
+// even another bare tag — and it wins automatically:
+//
+//   button { background: gold; }   // wins, (0,0,1) > (0,0,0)
+//
+// Heads up: bare-tag styling is global. If you mount third-party React
+// components that render their own <button> internally (Radix, react-select,
+// react-datepicker, cmdk), they WILL inherit these rules. Either skip this
+// recipe and write your own scoped wrappers, or scope this recipe by copying
+// it into a `.cia-prose { … }` block in your own SCSS.
+// ============================================================================
+@use '../mixins' as m;
+@use '../components/buttons' as b;
+@use '../components/forms' as f;
+@use '../components/data' as d;
+@use '../components/overlay' as o;
+
+// ----------------------------------------------------------------------------
+// TYPOGRAPHY
+// ----------------------------------------------------------------------------
+:where(h1) { @include m.type(heading-1); margin-block: m.space(5) m.space(3); }
+:where(h2) { @include m.type(heading-2); margin-block: m.space(5) m.space(3); }
+:where(h3) { @include m.type(heading-3); margin-block: m.space(4) m.space(2); }
+:where(h4) { @include m.type(heading-4); margin-block: m.space(4) m.space(2); }
+:where(h5) { @include m.type(heading-4); margin-block: m.space(3) m.space(2); }
+:where(h6) {
+  @include m.type(body);
+  font-weight: m.font-weight(semibold);
+  margin-block: m.space(3) m.space(2);
+}
+
+:where(p) {
+  margin-block: 0 m.space(3);
+}
+
+:where(small) {
+  font-size: m.font-size(2);
+}
+
+:where(blockquote) {
+  margin-block: m.space(4);
+  margin-inline: 0;
+  padding-block: m.space(2);
+  padding-inline: m.space(4);
+  border-inline-start: 4px solid m.color(border-default);
+  color: m.color(text-secondary);
+  font-style: italic;
+}
+
+// ----------------------------------------------------------------------------
+// CODE
+// ----------------------------------------------------------------------------
+:where(code, kbd, samp) {
+  font-family: m.font-family(mono);
+  font-size: 0.9em;
+  background: m.color(surface-subtle);
+  padding-inline: m.space(1);
+  border-radius: m.radius(sm);
+}
+
+:where(pre) {
+  font-family: m.font-family(mono);
+  font-size: m.font-size(2);
+  background: m.color(surface-subtle);
+  padding: m.space(3);
+  border-radius: m.radius(md);
+  overflow-x: auto;
+  margin-block: m.space(3);
+
+  :where(code) {
+    background: transparent;
+    padding: 0;
+    border-radius: 0;
+  }
+}
+
+// ----------------------------------------------------------------------------
+// LISTS
+// ----------------------------------------------------------------------------
+:where(ul, ol) {
+  margin-block: 0 m.space(3);
+  padding-inline-start: m.space(5);
+}
+
+:where(li) {
+  margin-block-end: m.space(1);
+}
+
+// ----------------------------------------------------------------------------
+// STRUCTURAL
+// ----------------------------------------------------------------------------
+:where(hr) {
+  border: none;
+  border-block-start: 1px solid m.color(border-default);
+  margin-block: m.space(5);
+}
+
+:where(figure) {
+  margin-block: m.space(4);
+  margin-inline: 0;
+}
+
+:where(figcaption) {
+  font-size: m.font-size(2);
+  color: m.color(text-secondary);
+  margin-block-start: m.space(1);
+}
+
+// ----------------------------------------------------------------------------
+// TABLES
+// ----------------------------------------------------------------------------
+:where(table) {
+  @include d.table-base;
+  margin-block: m.space(3);
+}
+
+// ----------------------------------------------------------------------------
+// FORMS — bare tags get base styling. Variants via class or @include.
+// ----------------------------------------------------------------------------
+:where(button) {
+  @include b.btn(primary);
+}
+
+:where(
+  input[type="text"],
+  input[type="email"],
+  input[type="password"],
+  input[type="search"],
+  input[type="tel"],
+  input[type="url"],
+  input[type="number"],
+  input[type="date"],
+  input[type="time"],
+  input[type="datetime-local"]
+) {
+  @include f.input-base;
+}
+
+:where(select)   { @include f.select-base; }
+:where(textarea) { @include f.textarea-base; }
+:where(label)    { @include f.label-base; }
+
+:where(fieldset) {
+  border: 1px solid m.color(border-default);
+  border-radius: m.radius(md);
+  padding: m.space(4);
+  margin-block: m.space(3);
+}
+
+:where(legend) {
+  padding-inline: m.space(2);
+  font-weight: m.font-weight(semibold);
+}
+
+// ----------------------------------------------------------------------------
+// INTERACTIVE
+// ----------------------------------------------------------------------------
+:where(details) {
+  margin-block: m.space(2);
+
+  > :where(summary) {
+    cursor: pointer;
+    padding: m.space(2);
+    font-weight: m.font-weight(medium);
+    border-radius: m.radius(md);
+    @include m.transition(background-color);
+
+    &:hover {
+      background: m.color(interactive-hover);
+    }
+  }
+
+  > :where(summary) + * {
+    padding: m.space(2);
+  }
+}
+
+// ----------------------------------------------------------------------------
+// V0.8 NATIVE COMPONENTS — sensible defaults for <dialog>, <progress>
+// ----------------------------------------------------------------------------
+// Round out Tier 3 for the v0.8 zero-JS component slate. Pair with the
+// existing component mixins (cia.modal, cia.progress) when richer styling
+// is needed.
+
+:where(dialog) {
+  @include o.modal-base;
+  border: 0;
+  margin: auto;
+
+  &::backdrop {
+    background: rgba(0, 0, 0, 0.5);
+    backdrop-filter: blur(2px);
+  }
+}
+
+:where(progress) {
+  inline-size: 100%;
+  block-size: 0.5rem;
+  appearance: none;
+  border: 0;
+  border-radius: m.radius(full);
+  background: m.color(surface-muted);
+  overflow: hidden;
+
+  &::-webkit-progress-bar {
+    background: m.color(surface-muted);
+    border-radius: m.radius(full);
+  }
+  &::-webkit-progress-value {
+    background: m.color(action-primary-default);
+    border-radius: inherit;
+    @include m.transition(inline-size, slow);
+  }
+  &::-moz-progress-bar {
+    background: m.color(action-primary-default);
+    border-radius: inherit;
+  }
+}

package/scss/recipes/_recipe-template.md

@@ -0,0 +1,119 @@
+---
+name: my-recipe-slug
+description: One sentence describing what this recipe builds.
+category: overlay
+complexity: medium
+cia-version: ">=1.0.0"
+---
+
+<!--
+Copy this file to <your-slug>.md (no leading underscore) and fill in each
+section. Required: name, description, category, complexity, cia-version
+frontmatter + all H2 sections below up to "Framework examples". Optional
+sections (Variants, Pitfalls, Related recipes) can be dropped if empty.
+
+See ./README.md for the full schema spec.
+-->
+
+## Use this when
+
+A short paragraph (1-3 sentences) describing the consumer scenario. If the
+reader's situation doesn't match what you describe, they should bail and
+look elsewhere. Be specific about what this recipe IS and ISN'T.
+
+## Structure (raw HTML)
+
+The markup with `data-slot` attributes for consumer hooks. Framework-agnostic;
+the consumer adapts to JSX / template / Svelte syntax.
+
+```html
+<element data-cia-recipe="my-recipe-slug">
+  <slot data-slot="title"></slot>
+  <slot data-slot="body"></slot>
+</element>
+```
+
+## Styling (cia mixins)
+
+```scss
+// MyThing.module.scss — component stylesheet, so import the zero-emit barrel.
+@use 'css-is-awesome/api' as cia;
+
+.my-thing {
+  @include cia.some-mixin(variant);
+}
+.my-thing [data-slot="title"] {
+  @include cia.type(heading-2);
+}
+```
+
+Show the minimum to make it work. Cross-link to mixin docs for parameter
+detail. Use consumer-chosen class names (`my-thing`), never `cia-*`.
+
+**Two imports, two jobs.** Component stylesheets always `@use
+'css-is-awesome/api'` — it is zero-emit, so it is safe inside a
+`.module.scss` under Next.js CSS Modules pure mode. The emitting bundle
+(`@use 'css-is-awesome'`) belongs in the app's root/global stylesheet, where
+it prints the `:root` tokens exactly once. If a recipe needs a mixin that
+emits at the root itself (e.g. `cia.print-base`, which emits `:root` +
+`@page`), say so in prose and show it in a global stylesheet — `/api` still
+forwards it.
+
+## Interactivity
+
+Describe the behavior. Prefer native browser primitives (`<dialog>`, popover
+API, `:has()`, radio + `:nth-of-type()`). JS only where the native primitive
+genuinely can't do the job.
+
+- Native: which APIs / pseudo-classes do the work
+- JS: when consumer needs a script, what it does, how small it can be
+- Edge cases: SSR safety, hydration timing, mobile gestures
+
+## A11y checklist
+
+Concrete, testable items. Each item references the WCAG SC or ARIA pattern.
+
+- [ ] item 1 — (WCAG 2.2 SC X.X.X reference or ARIA pattern URL)
+- [ ] item 2
+- [ ] item 3
+
+## Framework examples
+
+Minimum 4 subsections: React, Vue, Svelte, vanilla (Web Component preferred
+for vanilla). Each example must be runnable code, not pseudocode.
+
+### React
+
+```tsx
+// runnable React example
+```
+
+### Vue
+
+```vue
+<!-- runnable Vue example -->
+```
+
+### Svelte
+
+```svelte
+<!-- runnable Svelte example -->
+```
+
+### Vanilla (Web Component)
+
+```js
+// runnable Web Component example
+```
+
+## Variants
+
+(optional) Common adaptations. One sub-block per variant with the styling delta.
+
+## Pitfalls
+
+(optional) Known gotchas — SSR, browser compat, focus management edge cases.
+
+## Related recipes
+
+(optional) Cross-link to other recipes.