diff --git a/.agents/skills/fulldev/SKILL.md b/.agents/skills/fulldev/SKILL.md deleted file mode 100644 index 8b5e136aa..000000000 --- a/.agents/skills/fulldev/SKILL.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -name: fulldev -description: Apply Fulldev's content, schema, layout, component and block conventions in Astro client projects, and install UI from the @fulldev registry. ---- - -# Fulldev - -Follow the project's existing architecture and repository workflow. These are -Fulldev client conventions, not a request to migrate a project or change the -Fulldev UI library. Mention useful library improvements at handoff when relevant. - -Content owns copy and semantic configuration; schemas validate it; layouts map -it into component and block props. Components and blocks own rendering, -behavior and styles. Routes stay generic and the base layout stays a shared shell. - -Use existing `@fulldev` components and blocks before creating equivalents. -Install through shadcn using the project's `components.json`; see -[installation](cli.md) for shared setup and registry details. Read installed -source for the actual API. Local components are application code unless the -repository says otherwise. - -Read the relevant rules when changing: - -- [Content and schemas](rules/source-ownership.md): authored data, globals and icons. -- [Layouts and routes](rules/layouts.md): page orchestration and new page types. -- [Components](rules/components.md): Astro props, class forwarding and customization. -- [Blocks](rules/blocks.md): portable sections, semantic props and content mapping. - -Use the repository's own development and validation instructions. diff --git a/.agents/skills/fulldev/agents/openai.yaml b/.agents/skills/fulldev/agents/openai.yaml deleted file mode 100644 index 0e1355040..000000000 --- a/.agents/skills/fulldev/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "Fulldev" - short_description: "Fulldev Astro architecture and UI guidance" - default_prompt: "Use $fulldev while working in a Fulldev client project." diff --git a/.agents/skills/fulldev/cli.md b/.agents/skills/fulldev/cli.md deleted file mode 100644 index bbbedec7b..000000000 --- a/.agents/skills/fulldev/cli.md +++ /dev/null @@ -1,32 +0,0 @@ -# Install Fulldev UI - -Use the shadcn CLI with the project's package runner, such as `pnpm dlx shadcn@latest`. -There is no separate Fulldev CLI. When `components.json` is missing, initialize -from the Fulldev UI base in the project's style. It writes `components.json` -with the `@fulldev` registry, adds the theme tokens to the stylesheet in -`components.json`, and installs `cn` and the shared dependencies: - -```bash -pnpm dlx shadcn@latest init https://ui.full.dev/r/styles/base-vega/base.json -pnpm dlx shadcn@latest add @fulldev/button -``` - -When `components.json` exists, do not run `init`, because it replaces the theme -tokens. Set `style` to a `base-` style if it is a legacy or `radix-` style, add -the registry entry, then `add @fulldev/init`, which adds the helpers and base -styles and leaves the theme tokens alone: - -```json -{ - "registries": { - "@fulldev": "https://ui.full.dev/r/styles/{style}/{name}.json" - } -} -``` - -`@fulldev/components` and `@fulldev/blocks` are bulk installs, for requests that -need the full sets. - -Use shadcn's existing inspection and install tooling. `components.json` owns -registry URLs and aliases; adjust hardcoded imports from registry items to the -project's actual aliases. diff --git a/.agents/skills/fulldev/rules/blocks.md b/.agents/skills/fulldev/rules/blocks.md deleted file mode 100644 index 1fe3b839e..000000000 --- a/.agents/skills/fulldev/rules/blocks.md +++ /dev/null @@ -1,26 +0,0 @@ -# Blocks - -Blocks live in `src/components/blocks`. Layouts map schema-backed content into -plain block props and slots. Keep reusable blocks independent of page schemas, -collection types, content, layouts, routes and private project assets. Pass -images, labels, links, CTAs and content-owned icons through props when they vary -by project, page, instance or locale. Fixed control icons can be imported in code. - -Expose `class?: string`, destructure it as `class: className`, and forward it to -the outermost root through `cn(...)`, including `cn("", className)` without base -classes. Keep prop types plain and inline; do not import UI component prop types. - -Use `label` for controls, `title` for headings/entities, `description` for copy, -`icon` for content icon names, `href` for destinations and `buttons` for CTAs. -Name collections by their content, such as `features`, `services` or `reviews`; -use `items` only for genuinely generic data. - -These naming rules apply to data. Preserve CSS utilities, selectors, `data-*` -attributes, slots, component/file names and style hooks. `items-center` must -remain `items-center`, never `features-center`. - -Button size belongs to the block design, not content data. Derive `target`/`rel` -from `href` in the component when needed. Render direct mappings inline; derive -named values in frontmatter for sorting, filtering, combining sources, active -state and schema-to-block transformations. Guard optional values, and map -required arrays directly. diff --git a/.agents/skills/fulldev/rules/components.md b/.agents/skills/fulldev/rules/components.md deleted file mode 100644 index 5aedbcae6..000000000 --- a/.agents/skills/fulldev/rules/components.md +++ /dev/null @@ -1,19 +0,0 @@ -# Components - -Use `src/components/ui//`, kebab-case filenames, an `index.ts` -public API and colocated helpers. Follow the project's actual import aliases. - -- Define local `type Props` before destructuring `Astro.props` once. Export it - from an `.astro` file only if an external TypeScript module imports it. -- Let Astro infer props without `: Props` on the destructuring or `as Props`. - For a complex type, simplify its shape or use `satisfies Props`. -- Use Astro's `HTMLAttributes` or `Polymorphic` helpers for native attributes. -- Destructure `class` as `class: className`, call the remaining pass-through bag - `props`, merge classes with `cn(...)`, and spread `props` on the intended root - or control. Preserve required `data-slot` structure and behavior. -- Keep content-specific data out of generic primitives. Use built-in props and - composition first; local wrappers can hold project-specific behavior. - -Customize global appearance in the existing theme's semantic CSS variables; -use component variants for component choices and layouts for page composition. -Do not introduce a second theme layer for a local customization. diff --git a/.agents/skills/fulldev/rules/layouts.md b/.agents/skills/fulldev/rules/layouts.md deleted file mode 100644 index f552e67a8..000000000 --- a/.agents/skills/fulldev/rules/layouts.md +++ /dev/null @@ -1,19 +0,0 @@ -# Layouts and routes - -`src/pages/[...page].astro` fetches and renders content, loads globals, resolves -`src/layouts/.astro` from `page.data.type`, and passes `global`, `page`, -`headings` and `` to it. Keep the route and any layout renderer generic. - -Layouts choose sections, shape data and map validated content into block props. -Keep page-specific SEO and icon mapping here. In Astro frontmatter, use local -`type Props` with `global: GlobalSchema` and the specific layout schema for -`page`. Destructure `Astro.props` directly; omit unused props. Include required -`headings: MarkdownHeading[]` only in layouts that use them. - -`src/layouts/base.astro` owns the shared document shell, head, navigation and -theme. Forward `page.seo` directly to head components; keep page-specific SEO -fallbacks, content reshaping and layout branching out of the base shell. - -For a new page type, add `src/schemas/layouts/.ts` to the union in -`src/schemas/page.ts`, create `src/layouts/.astro`, and add page content -with `type: `. The generic route should need no change. diff --git a/.agents/skills/fulldev/rules/source-ownership.md b/.agents/skills/fulldev/rules/source-ownership.md deleted file mode 100644 index df3e97054..000000000 --- a/.agents/skills/fulldev/rules/source-ownership.md +++ /dev/null @@ -1,21 +0,0 @@ -# Content and schemas - -- Page content lives in `src/content/pages`; cross-page, locale-aware data such - as navigation and footer copy lives in `src/content/globals`. Keep page-specific - block data with its page. -- Prefer Markdown with structured frontmatter and body content. Layouts render - the body with ``. Use MDX imports/components only for docs or live - code examples that need them. -- Frontmatter holds schema-validated semantic values, not Tailwind classes, - raw HTML/SVG, imported icons or component/DOM implementation details. -- Schemas live in `src/schemas`, with layout schemas in `src/schemas/layouts`. - `src/content.config.ts` connects collections to schemas; `src/schemas/page.ts` - contains the page union discriminated by frontmatter `type`. -- Validate object shape strictly; keep open-ended ecosystem values such as icon - names permissive where appropriate. - -Content-owned icons are plain names rendered through `src/components/ui/icon`, -for example ``. Preserve its name normalization, -Lucide default and Simple Icons fallback for brand/social icons. Import fixed -control icons directly from static SVG packages with an `Icon` suffix, such as -`ArrowRightIcon`. Content determines meaning; code owns control behavior. diff --git a/.agents/skills/ui-upstream-sync/SKILL.md b/.agents/skills/ui-upstream-sync/SKILL.md index 810d1378b..51d1976ad 100644 --- a/.agents/skills/ui-upstream-sync/SKILL.md +++ b/.agents/skills/ui-upstream-sync/SKILL.md @@ -1,6 +1,8 @@ --- name: ui-upstream-sync description: Audit and update the existing Fulldev Astro UI registry against current data-slot and shadcn/ui Base UI Vega. Use for periodic whole-library upstream parity passes, not ordinary single-component edits. +metadata: + internal: true --- # Fulldev UI upstream sync @@ -14,7 +16,7 @@ Use this skill only in the Fulldev UI registry source. The goal is a deliberate - Treat Base UI with the Vega style as the shadcn comparison baseline. Do not accept the current CLI default if it differs. - Preserve Astro APIs, data-slot behavior, forwarded props, state attributes, keyboard behavior, and accessibility. - Port useful HTML, classes, variants, and public defaults. Do not port React-only state, refs, hooks, or composition that conflicts with data-slot. -- Do not copy theme-dependent classes unless this repo defines the required token. For example, `font-heading` is a no-op without a heading-font mapping. +- Do not copy theme-dependent classes unless this repo defines the required token. - Treat `registry.json` as source and `public/r` as generated output. Never hand-edit generated registry files. ## Prepare the audit @@ -39,18 +41,12 @@ Use this skill only in the Fulldev UI registry source. The goal is a deliberate ## Pass 2: shadcn/ui -1. Create a throwaway project outside the repo with `mktemp -d`. -2. Inspect current CLI help, then create a Vite project using Base UI and the Vega preset. The last known form is: - - ```bash - pnpm dlx shadcn@latest create --template vite --base base --preset vega - pnpm dlx shadcn@latest add --all - ``` - -3. Use `pnpm dlx shadcn@latest docs ` for current official component docs. +1. In a throwaway directory outside the repo (`mktemp -d`), scaffold a Vite project with Base UI and the Vega style and install every component, as the shadcn skill describes. +2. Copy the current shadcn style files into `registry/styles/shadcn/` as `registry/styles/README.md` describes. +3. Use `shadcn docs ` for current official component docs. 4. Intersect the scratch project's components with this repo's existing families. Do not expand the audit to missing components. 5. Compare each matching family sequentially. Check markup order, class names, variants, sizes, default props, data attributes, focus and validation states, icon treatment, RTL behavior, and accessibility. -6. Adapt relevant differences to Astro and data-slot. Record intentional differences instead of forcing literal parity. +6. Adapt relevant differences to Astro and data-slot. Make visual changes through the placeholders and style files in `registry/styles/README.md`; never paste rendered Vega classes into component source. Record intentional differences instead of forcing literal parity. ## Registry and generated output @@ -65,8 +61,7 @@ Use this skill only in the Fulldev UI registry source. The goal is a deliberate ## Validation and handoff 1. Format settled source and manifest changes. -2. Follow the release validation order in `AGENTS.md`. +2. Run `pnpm check`. 3. Run the dev server and inspect every changed component page in a real browser. Exercise relevant keyboard, pointer, open and close, selection, disabled, and RTL behavior. Check the browser console and server logs. -4. Use the Otis sharing instruction in `AGENTS.md` when the user needs tailnet access. -5. Give a concise per-family report. For each changed family, name the source change, whether it came from data-slot, shadcn, registry metadata, or more than one, and include its preview URL. -6. Also list reviewed unchanged families, validation results, intentional differences, generated-only drift, and release blockers. +4. Give a concise per-family report. For each changed family, name the source change, whether it came from data-slot, shadcn, registry metadata, or more than one, and include its preview URL. +5. Also list reviewed unchanged families, validation results, intentional differences, generated-only drift, and release blockers. diff --git a/AGENTS.md b/AGENTS.md index 91711840d..0b42ca665 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # Fulldev UI -This repository is the Fulldev UI registry source, docs site and reference implementation. For conventions in client projects, use the `fulldev` skill in `.agents/skills`. +This repository is the Fulldev UI registry source, docs site and reference implementation. `skills/fulldev-ui` is the public skill for projects that use Fulldev UI; keep it in line with the docs when behavior changes. ## Components diff --git a/README.md b/README.md index 514d11d8b..1e620ae36 100644 --- a/README.md +++ b/README.md @@ -70,6 +70,13 @@ npx shadcn@latest add @fulldev/button Visit [ui.full.dev][docs] for complete documentation, component examples, and usage guides. +For coding agents, install the shadcn skill and the Fulldev UI skill: + +```bash +npx skills add shadcn/ui +npx skills add fulldotdev/ui --skill fulldev-ui +``` + ## Development Requires Node 24 (`.node-version`) and pnpm 12. The published package supports Node 22.12+. Installs never run dependency or project lifecycle scripts (`pnpm-workspace.yaml`). diff --git a/skills/fulldev-ui/SKILL.md b/skills/fulldev-ui/SKILL.md new file mode 100644 index 000000000..ca7813091 --- /dev/null +++ b/skills/fulldev-ui/SKILL.md @@ -0,0 +1,85 @@ +--- +name: fulldev-ui +description: Use together with the shadcn skill in projects that use Fulldev UI, the @fulldev registry of Astro components and blocks, or its React extension. Covers installing, presets, theming, customizing and writing blocks where Fulldev UI differs from shadcn/ui. Applies when components.json has an @fulldev registry. +--- + +# Fulldev UI + +Fulldev UI is shadcn/ui for Astro: the same tokens, styles, presets and CLI, +plus content components, such as section, banner, header and typography, and +page blocks. Its React extension adds those extras and blocks to an official +shadcn/ui React project. + +Use the [shadcn skill](https://github.com/shadcn-ui/ui/tree/main/skills/shadcn) +for the CLI, registries, semantic tokens and design principles. For Astro +component APIs, read the installed source and the docs at +`https://ui.full.dev/components/.md`; `shadcn docs` describes the React +components. Start at [llms.txt](https://ui.full.dev/llms.txt), or +[react/llms.txt](https://ui.full.dev/react/llms.txt) for React. Where this skill +and the shadcn skill differ, this skill wins. + +## Astro setup + +- Fulldev UI serves only the Base UI styles (`base-vega`, `base-nova` and so + on) with Lucide icons. Move a legacy style, such as `new-york`, or a `radix-` + style to a `base-` style first; see + [Presets](https://ui.full.dev/docs/presets.md). +- The registry is `https://ui.full.dev/r/styles/{style}/{name}.json`. An older + URL without `{style}` always installs Vega. +- Start a project with + `init https://ui.full.dev/r/styles/base-