eddev 2.3.12 → 2.3.13

package/skills/eddev/docs/design/color.mdx

@@ -0,0 +1,185 @@
+# Colours (/docs/design/color)
+
+**Configure colour tokens and Figma handoff output for Tailwind.**
+
+Current eddev themes still use Tailwind v3, so design tokens are wired through
+`tailwind.config.ts`. The starter theme currently includes `tailwind-helper/`,
+and real sites copy or adjust that helper in the theme rather than relying on a
+shared package.
+
+The Figma handoff plugin can produce ED. Tailwind snippets for colours,
+typography, spacing, size, and radius tokens. Treat that output as a starting
+point, then keep the final contract in `tailwind.config.ts`.
+
+## Configuration [#configuration]
+
+Import `responsiveTheme` from the local helper and pass colour tokens into the
+plugin config.
+
+```ts filename="tailwind.config.ts"
+import ContainerQueries from "@tailwindcss/container-queries"
+import { Config } from "tailwindcss"
+import { responsiveTheme } from "./tailwind-helper/plugin"
+
+export default {
+  content: [
+    "./views/**/*.{ts,tsx}",
+    "./blocks/**/*.{ts,tsx}",
+    "./components/**/*.{ts,tsx}",
+    "./backend/**/*.{ts,tsx}",
+    "./features/**/*.{ts,tsx}",
+    "./utils/**/*.{ts,tsx}",
+  ],
+  plugins: [
+    responsiveTheme({
+      screens: { sm: 600, md: 900, lg: 1200, xl: 1600, xxl: 2000 },
+      breakpoints: ["lg"],
+      interpolate: {
+        sm: {},
+        md: { base: "sm", lerp: true },
+        lg: { base: "lg", lerp: true },
+        xl: { base: "lg", lerp: true },
+        xxl: { base: "lg" },
+      },
+      colors: {
+        base: {
+          black: "#212121",
+          white: "#ffffff",
+          grey: {
+            DEFAULT: "#757575",
+            light: "#ecebea",
+            dark: "#585858",
+          },
+          glass: "#f9f9f9",
+        },
+        semantic: {
+          bg: "glass",
+          fg: "black",
+          muted: "grey",
+        },
+        subthemes: {
+          "theme-dark": {
+            bg: "black",
+            fg: "glass",
+            muted: "grey",
+          },
+        },
+      },
+    }),
+    ContainerQueries,
+  ],
+} satisfies Config
+```
+
+`base` colours become normal Tailwind colour names such as `text-black`,
+`bg-grey-light`, and `border-grey-dark`. Nested `DEFAULT` values are exposed as
+the parent name.
+
+The helper stores colours as CSS variables using Tailwind's alpha-aware colour
+format, so opacity modifiers keep working:
+
+```tsx
+<div className="bg-grey-light text-black">
+  <p className="text-black/60">Secondary text</p>
+</div>
+```
+
+Use solid hex or `rgb(...)` values for generated colour tokens.
+
+## Figma Export [#figma-export]
+
+Open `Plugins -> From ED. -> ED. Web Handoff` in Figma and use the Colours
+panel. The plugin reads local paint styles and colour variables, reports naming
+or unsupported-fill issues, and shows an ED. Tailwind code block.
+
+Naming rules to keep exports clean:
+
+| Figma Source                | Tailwind Token                                     |
+| --------------------------- | -------------------------------------------------- |
+| `Black`                     | `black`                                            |
+| `Grey/Light`                | `grey.light` in config, `bg-grey-light` in classes |
+| `Grey/Default`              | `grey.DEFAULT` in config, `bg-grey` in classes     |
+| Theme variable `Background` | `bg` semantic token                                |
+
+Paint styles or variables whose name starts with `_`, or contains `/_`, are
+ignored by the extractor. Use that for design-only swatches that should not
+ship as code tokens.
+
+## Semantic Colours [#semantic-colours]
+
+Semantic colours are the theme-ready layer. Use them when a component or
+section should adapt to a subtheme or colour scheme rather than lock itself to
+specific named colours.
+
+```tsx
+export function Panel(props: { children: React.ReactNode }) {
+  return (
+    <section className="theme-dark bg-bg text-fg p-5 rounded-md">
+      {props.children}
+    </section>
+  )
+}
+```
+
+The `semantic` map defines the default CSS variables:
+
+```ts filename="tailwind.config.ts"
+colors: {
+  semantic: {
+    bg: "glass",
+    fg: "black",
+    "fg-secondary": "grey",
+  },
+}
+```
+
+The helper adds `--color-bg`, `--color-fg`, and matching Tailwind colours. A
+subtheme class overrides the same variables inside that subtree.
+
+## Subthemes [#subthemes]
+
+Subthemes are Tailwind classes that remap semantic colour variables inside a
+subtree. They let the same component keep using classes such as `bg-bg`,
+`text-fg`, and `text-fg-secondary` while the wrapper decides which base colours
+those classes resolve to.
+
+Subtheme keys are literal class names. If the key is `"theme-dark"`, the class
+is `.theme-dark` and the generated ancestor variant is `is-theme-dark:`.
+
+```ts filename="tailwind.config.ts"
+colors: {
+  subthemes: {
+    "theme-light": {
+      bg: "white",
+      fg: "black",
+      "fg-secondary": "grey",
+    },
+    "theme-dark": {
+      bg: "black",
+      fg: "white",
+      "fg-secondary": "grey.light",
+    },
+  },
+}
+```
+
+```tsx
+<section className="theme-dark bg-bg text-fg">
+  <h2 className="type-title-l">Dark section</h2>
+  <a className="text-fg-secondary hover:text-fg">Read more</a>
+</section>
+```
+
+Use the generated `is-*` variants when a child needs to react to an ancestor
+theme:
+
+```tsx
+<article className="bg-orange text-fg is-theme-dark:theme-light is-theme-dark:bg-white">
+  ...
+</article>
+```
+
+<Callout type="info">
+  For author-selectable schemes and TypeScript mapping helpers, see
+  [Colour Schemes](/docs/guides/color-schemes).
+</Callout>

package/skills/eddev/docs/design/favicons.mdx

@@ -0,0 +1,103 @@
+# Favicons (/docs/design/favicons)
+
+**Configure how eddev generates or delegates favicon assets.**
+
+eddev can either leave favicons to WordPress, generate them from SVG sources,
+or generate them from a set of PNG files. The mode is configured in
+`ed.config.json`.
+
+```json filename="ed.config.json"
+{
+  "$schema": ".ed.config.schema.json",
+  "version": "2",
+  "favicon": {
+    "mode": "svg"
+  }
+}
+```
+
+## Modes [#modes]
+
+| Mode   | Use When                                                                              |
+| ------ | ------------------------------------------------------------------------------------- |
+| `auto` | WordPress Site Icon should handle favicons. eddev does not generate `.ico` output.    |
+| `svg`  | The project has a single SVG favicon source, optionally with light and dark variants. |
+| `pngs` | The project has a prepared set of PNG favicon files.                                  |
+
+`auto` is the schema default, but current sites that keep favicon assets in the
+theme should set the mode explicitly.
+
+## SVG Favicons [#svg-favicons]
+
+SVG mode uses these default paths:
+
+| Config Field | Default                     |
+| ------------ | --------------------------- |
+| `default`    | `/assets/favicon.svg`       |
+| `light`      | `/assets/favicon-light.svg` |
+| `dark`       | `/assets/favicon-dark.svg`  |
+
+```json filename="ed.config.json"
+{
+  "favicon": {
+    "mode": "svg",
+    "default": "/assets/favicon.svg",
+    "light": "/assets/favicon-light.svg",
+    "dark": "/assets/favicon-dark.svg"
+  }
+}
+```
+
+The SVG is linked directly for modern browsers, and eddev generates a raster
+`.ico` for compatibility. If light and dark variants are provided, the `.ico`
+uses the default/light source.
+
+A single SVG can also carry its own colour-scheme media query:
+
+```tsx filename="assets/favicon.svg"
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
+  <style>
+    .icon-dark { display: none; }
+    @media (prefers-color-scheme: dark) {
+      .icon-light { display: none; }
+      .icon-dark { display: inline; }
+    }
+  </style>
+  <g class="icon-light">...</g>
+  <g class="icon-dark">...</g>
+</svg>
+```
+
+## PNG Favicons [#png-favicons]
+
+PNG mode collects files from these default globs:
+
+| Config Field | Default                               |
+| ------------ | ------------------------------------- |
+| `default`    | `/assets/favicon/favicon-*.png`       |
+| `light`      | `/assets/favicon/favicon-*-light.png` |
+| `dark`       | `/assets/favicon/favicon-*-dark.png`  |
+
+```json filename="ed.config.json"
+{
+  "favicon": {
+    "mode": "pngs",
+    "default": "/assets/favicon/favicon-*.png"
+  }
+}
+```
+
+Use PNG mode when the design handoff already includes multiple raster sizes
+such as `favicon-16x16.png`, `favicon-32x32.png`, and Apple touch icons.
+
+## Theme Colour [#theme-colour]
+
+Favicons do not set the browser theme colour. Add that separately from PHP if
+the site needs it:
+
+```php filename="backend/head.php"
+<?php
+add_action("wp_head", function () {
+  echo '<meta name="theme-color" content="#000000">';
+});
+```

package/skills/eddev/docs/design/grid.mdx

@@ -0,0 +1,120 @@
+# Grid System (/docs/design/grid)
+
+**Configure grid tokens, gutters, and layout utilities.**
+
+The grid is configured through the local `tailwind-helper` in
+`tailwind.config.ts`. Current projects use Tailwind v3, so this config file is
+still the source of truth for breakpoints, gutters, margins, and generated grid
+utilities.
+
+## Configuration [#configuration]
+
+```ts filename="tailwind.config.ts"
+responsiveTheme({
+  screens: { sm: 600, md: 900, lg: 1200, xl: 1600, xxl: 2000 },
+  breakpoints: ["lg"],
+  interpolate: {
+    sm: {},
+    md: { base: "sm", lerp: true },
+    lg: { base: "lg", lerp: true },
+    xl: { base: "lg", lerp: true },
+    xxl: { base: "lg" },
+  },
+  grid: {
+    BASE: {
+      container: "100vw",
+      gutter: "16px",
+      margin: "16px",
+    },
+    EDITOR: {
+      container: "var(--vw100)",
+      gutter: "16px",
+      margin: "16px",
+    },
+    md: {
+      container: "100vw",
+      gutter: "24px",
+      margin: "24px",
+    },
+    lg: {
+      container: "100vw",
+      gutter: "2vw",
+      margin: "2vw",
+    },
+    xxl: {
+      container: "2000px",
+      gutter: "32px",
+      margin: "32px",
+    },
+  },
+})
+```
+
+`BASE` is the normal mobile value. `EDITOR` is applied inside the WordPress
+admin, where viewport sizing can differ from the frontend. Other keys map to
+the configured Tailwind screens.
+
+The helper writes CSS variables such as `--tw-grid-container`,
+`--tw-grid-margin`, `--tw-grid-gutter`, and `--tw-grid-col-width`. Tailwind
+classes are then built on top of those variables.
+
+## Layout Classes [#layout-classes]
+
+Use `grid-auto` for the standard 12-column site grid.
+
+```tsx
+<section className="grid-auto py-grid-margin">
+  <div className="col-span-12 md:col-span-8">
+    <h1 className="type-title-xl">Page title</h1>
+  </div>
+  <aside className="col-span-12 md:col-span-4">
+    ...
+  </aside>
+</section>
+```
+
+Common helper classes:
+
+| Class                       | Use                                                |
+| --------------------------- | -------------------------------------------------- |
+| `grid-auto`                 | Standard centred 12-column CSS grid.               |
+| `grid-container`            | Centred container width without creating a grid.   |
+| `grid-breakout`             | Expand an element out to the grid margin.          |
+| `grid-pl`                   | Add left grid margin padding.                      |
+| `col-span-*`                | Span 1 to 12 columns.                              |
+| `col-start-*` / `col-end-*` | Manually place a grid item.                        |
+| `auto-cols-*`               | Change the active column count for nested layouts. |
+
+Spacing keys are also exposed, so layout code can use `w-grid`,
+`px-grid-margin`, `gap-grid-gutter`, and `pb-grid-margin-full`.
+
+## Column Widths [#column-widths]
+
+The helper adds fixed column size utilities from the current grid variables:
+
+```tsx
+<div className="w-grid mx-auto">
+  <div className="w-cols-6">Six-column width</div>
+  <div className="w-col">One-column width</div>
+</div>
+```
+
+These widths are useful for cards, media blocks, and controls that need to align
+to the same rhythm as the grid without becoming grid children.
+
+## Blocks And Admin [#blocks-and-admin]
+
+Blocks often need separate frontend and editor layout classes. Use normal
+`className` for the frontend and `adminClassName` where eddev block helpers
+provide it.
+
+```tsx
+<InnerBlocks
+  className="grid-auto gap-y-grid-gutter"
+  adminClassName="grid col-span-12 gap-grid-gutter"
+  allowedBlocks={["content/card-grid-item"]}
+/>
+```
+
+Keep full-width blocks responsible for their outer background, then place
+content on the grid inside the block.

package/skills/eddev/docs/design/icons.mdx

@@ -0,0 +1,197 @@
+# Using Icons (/docs/design/icons)
+
+**Export and use Figma icons as React-friendly SVG components.**
+
+## Icons from Figma [#icons-from-figma]
+
+The ED. Web Handoff Figma plugin exports icon code from Figma as a single
+React/TypeScript file, along with a helper `<Icon />` component.
+
+When an exported SVG only uses one colour, the export replaces `fill` and
+`stroke` with `currentColor`. This is ideal for UI glyphs, but it is not a good
+fit for multi-colour illustrations.
+
+### Artworking [#artworking]
+
+The export requires that icons have been artworked correctly, with these requirements:
+
+1. Icons must be defined as individual Figma components.
+2. Icon component names must be named `Icon/{name}` or `Icons/{name}`, eg. `Icon/User`.
+3. Icons must live in the `⚛️ UI Kit` page.
+
+<Callout type="warning">
+  If these requirements are not met, then the Figma plugin will not find the icons.
+</Callout>
+
+### Exporting Process [#exporting-process]
+
+<Steps>
+  <Step>
+    ### Open the Plugin [#open-the-plugin]
+
+    In *Figma Design Mode*, navigate to 'Plugins → From ED. → ED. Web Handoff'.
+  </Step>
+
+  <Step>
+    ### Preview Icons [#preview-icons]
+
+    Select 'Icons' from the sidebar. Verify that the icons display correctly.
+
+        <img alt="Icon Listing" src="__img0" />
+  </Step>
+
+  <Step>
+    ### Export [#export]
+
+    Click 'Get Code'.
+
+        <img alt="Code Export" src="__img1" />
+  </Step>
+
+  <Step>
+    ### Copy and Paste [#copy-and-paste]
+
+    Copy and paste the output into your codebase, into a single file. If the icons are adjusted later, you can come back and repeat the process again, overriding the file.
+  </Step>
+</Steps>
+
+### Development [#development]
+
+#### `<Icon />` [#icon-]
+
+The generated file contains an `Icon` component. You can use this component like so:
+
+```tsx
+import { Icon, IconClose } from '~/components/atoms/icons'
+
+// Icon colour will inherit text color
+<Icon name="plus" />
+
+// Override icon colour
+<Icon name="delete" className="text-red" />
+
+// Render an icon directly
+<IconClose />
+```
+
+<Callout type="info">
+  Note that in the example above, if `icon` is `undefined`, the `<Icon />` component will render `null`.
+</Callout>
+
+#### `IconName` and `IconRef` [#iconname-and-iconref]
+
+The `IconName` and `IconRef` types can be used for type-safety when creating components that accept icons as props.
+
+Here's an example of what the Figma plugin generates:
+
+```typescript filename="icons.ts"
+// The `IconName` type is a union of the icon names, camel-cased.
+export type IconName =
+  | "close"
+  | "dot"
+  | "down"
+  | "menu"
+  | "plus"
+  | "right"
+  | "circleClose"
+  | "circleMinus"
+  | "circlePlus"
+
+// The `IconRef` type accepts either an icon name, or a JSX element like <svg />
+export type IconRef = IconName | ReactElement
+```
+
+You can use the `IconName` like so:
+
+```tsx
+import { type IconName } from '~/components/atoms/icons'
+
+type Props = {
+  icon?: IconName
+  label: string
+}
+
+export function Button(props: Props) {
+  return <button>
+    <Icon name={props.icon} />
+    {props.label}
+  </button>
+}
+
+// Usage with an icon:
+<Button icon="plus" label="Add" />
+
+// Without an icon:
+<Button label="Add" />
+
+// ❌ TypeScript error:
+<Button icon="jshfkajsdhfahsdf" label="Add" />
+```
+
+Alternatively, if your component should *also* accept icons from other component libraries, or inline-svg, you can use `IconRef` instead.
+
+```tsx
+import { type IconRef } from '~/components/atoms/icons'
+
+type Props = {
+  icon?: IconRef
+  label: string
+}
+
+export function Button(props: Props) {
+  return <button>
+    <Icon name={props.icon} />
+    {props.label}
+  </button>
+}
+
+// Usage with an icon name:
+<Button icon="plus" label="Add" />
+
+// Usage with an icon component
+<Button icon={<IconPlus />} label="Add" />
+
+// Usage with an arbitrary SVG
+<Button icon={<svg />} label="Add" />
+```
+
+You can also create your own subset of icon names, based on some prefix:
+
+```typescript
+export type CircleIcon = Extract<IconName, `circle${string}`>
+// ^ type CircleIcon = "circleClose" | "circleMinus" | "circlePlus"
+```
+
+#### `const ICONS` [#const-icons]
+
+Finally, you can also access the full set of icons using the `ICONS` variable that is exported.
+
+```tsx
+import { ICONS } from '~/components/atoms/icons'
+
+<select>
+  {Object.keys(ICONS).map(name => (
+    <option key={name} value={name}>{name}</option>
+  ))}
+</select>
+```
+
+#### Icon Styles [#icon-styles]
+
+For one-off styles, add `className` to the icon when it is used.
+
+```tsx
+<Icon name="delete" className="size-6 text-red" />
+```
+
+You can also apply global styling to all icons, since an `.icon` class name is automatically added to every icon rendered with the `<Icon />` component:
+
+```css filename="index.css"
+@layer components {
+  .icon {
+    @apply block flex-none aspect-square size-[1.5em];
+  }
+}
+```
+
+The example above ensures that icons don't grow/shrink when used in a flex container, and scale up and down automatically based on font size (which you may or may not want).