opencode-design-system 0.1.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +7 -40
  2. package/dist/index.js +7 -91
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -14,7 +14,7 @@ Con OpenCode v2, instala directamente desde el repositorio público:
14
14
  opencode plugin add github:BraveOtter/opencode-design-system
15
15
  ```
16
16
 
17
- Para fijar la versión inicial cuando esté publicada, usa `opencode plugin add github:BraveOtter/opencode-design-system#v0.1.0`.
17
+ Para fijar la versión `1.0.1` cuando esté publicada, usa `opencode plugin add github:BraveOtter/opencode-design-system#v1.0.1`.
18
18
 
19
19
  ### Paquete publicado
20
20
 
@@ -38,7 +38,7 @@ npm install
38
38
  npm run build
39
39
  ```
40
40
 
41
- Este checkout incluye `opencode.jsonc` para cargar `./plugins/local`, un entrypoint local que reexporta `dist/index.js`. Después de compilar, inicia OpenCode desde la raíz del repositorio para probar los comandos. Ese entrypoint de desarrollo no forma parte del paquete publicado.
41
+ Este checkout incluye `plugins/local/index.js` como entrypoint opcional para probar el build local; no se activa por defecto, para evitar cargar una copia local junto al paquete npm global. No forma parte del paquete publicado.
42
42
 
43
43
  Apunta OpenCode al directorio del paquete:
44
44
 
@@ -84,32 +84,13 @@ Implementación V2 basada en las APIs oficiales actuales:
84
84
  - `Plugin.define({ id, setup })` para el entrypoint del paquete.
85
85
  - `ctx.command.transform` para commands.
86
86
  - `ctx.tool.transform` para herramientas de creación, lectura progresiva, análisis, actualización, preview, comprobación y especificaciones de pantalla.
87
- - `ctx.skill.transform` para anunciar la Skill de uso del sistema.
88
- - `ctx.session.hook("context", ...)` para indicar a los agentes que usen la Skill cuando ya exista un manifest, sin inyectar todos los archivos.
89
- - Markdown estándar bajo `.opencode/agents`, `.opencode/commands` y `.opencode/skills` para hacer que los artefactos sobrevivan a la desinstalación.
87
+ - `ctx.session.hook("context", ...)` para apuntar a la guía de `AGENTS.md` cuando ya exista un manifest, sin copiar recursos del plugin al proyecto ni inyectar todos los archivos.
90
88
 
91
89
  No se ejecutan migraciones de componentes de la aplicación. El análisis del proyecto está acotado y solo lee archivos candidatos de UI/estilos, configuraciones conocidas y dependencias declaradas.
92
90
 
93
- ### Agentes
91
+ ### Portabilidad entre agentes
94
92
 
95
- Al crear el sistema se generan agentes V2 estándar:
96
-
97
- - `design-system-designer`: diseñador UI/UX, arquitecto, especialista en accesibilidad e interlocutor para decisiones de identidad.
98
- - `screen-designer`: genera especificaciones de pantalla y mantiene separado el diseño de su implementación.
99
-
100
- Los agentes son subagentes Markdown descubiertos por OpenCode, no dependen de un formato privado del plugin. Los commands incluyen las instrucciones de trabajo necesarias desde la primera sesión, antes de que esos archivos existan.
101
-
102
- ### Skill
103
-
104
- La Skill `design-system` dirige a cualquier agente a:
105
-
106
- 1. Comprobar el manifest.
107
- 2. Leer las reglas y preferencias.
108
- 3. Cargar solo los tokens, componentes y patterns ligados a la tarea.
109
- 4. Respetar decisiones explícitas y documentar cambios reutilizables.
110
- 5. Tratar una especificación de pantalla como un artefacto distinto del código.
111
-
112
- No carga permanentemente todas las tablas, componentes y patrones en el contexto. El `manifest.json` sirve como índice para recuperación progresiva.
93
+ Al crear el sistema, el plugin solo escribe `design-system/` y agrega o actualiza el bloque administrado de `AGENTS.md`. Ese bloque enlaza el manifest y explica a cualquier agente —OpenCode u otro— cómo cargar la guía y solo los tokens, componentes y patrones pertinentes. No genera agentes, commands ni skills dentro del proyecto; los commands del plugin existen únicamente mientras el plugin está instalado en OpenCode.
113
94
 
114
95
  ## Formato generado
115
96
 
@@ -140,18 +121,6 @@ design-system/
140
121
  └── generate-preview.mjs
141
122
 
142
123
  AGENTS.md # Bloque administrado, conserva el contenido previo
143
- .opencode/
144
- ├── agents/
145
- │ ├── design-system-designer.md
146
- │ └── screen-designer.md
147
- ├── commands/
148
- │ ├── design-system.md
149
- │ ├── design-system/update.md
150
- │ ├── design-system/preview.md
151
- │ ├── design-system/check.md
152
- │ └── design-screen.md
153
- └── skills/
154
- └── design-system/SKILL.md
155
124
  ```
156
125
 
157
126
  `manifest.json` incluye versiones, estado, temas, archivos y referencias de tokens por componente/pattern. Los estados son `draft`, `review` y `stable`. El schema base usa `schemaVersion: "1.0.0"`; la versión del sistema comienza en `0.1.0`.
@@ -224,7 +193,7 @@ Este renderer no tiene dependencias externas; lee el manifest, los tokens y docu
224
193
 
225
194
  `/design-screen` crea únicamente `design-system/screens/<nombre>.md`. La especificación incluye propósito, layout, jerarquía, componentes/tokens, contenido/datos, estados/interacciones, responsive y accesibilidad. Otro agente de programación puede implementar ese brief después.
226
195
 
227
- Cuando un agente de código recibe una solicitud UI ordinaria, `AGENTS.md` y la Skill del proyecto le indican cómo detectar el sistema y cargar solo lo relevante. Este mecanismo también funciona sin el plugin: los tokens y documentación no dependen de React, Vue, Tailwind u OpenCode.
196
+ Cuando un agente de código recibe una solicitud UI ordinaria, `AGENTS.md` le indica cómo descubrir el sistema y cargar solo lo relevante. Este mecanismo también funciona sin el plugin —y con agentes distintos de OpenCode— porque los tokens y la documentación no dependen de React, Vue, Tailwind u OpenCode.
228
197
 
229
198
  ## Comprobación
230
199
 
@@ -239,13 +208,11 @@ npm test
239
208
  npm run build
240
209
  ```
241
210
 
242
- Los tests ejercitan un flujo integrado en un proyecto temporal: análisis de UI existente, creación y preservación de archivos, instrucción `AGENTS.md`, creación de especificación, propagación de token entre temas, dependencias, preview, checks y protección de rutas.
211
+ Los tests ejercitan un flujo integrado en un proyecto temporal: análisis de UI existente, creación del Design System sin crear recursos `.opencode`, preservación de archivos existentes, actualización del bloque `AGENTS.md`, creación de especificación, propagación de token entre temas, preview, checks y protección de rutas.
243
212
 
244
213
  ## Documentación oficial de OpenCode v2
245
214
 
246
215
  - [Plugins](https://opencode.ai/v2/docs/build/plugins)
247
216
  - [Commands](https://opencode.ai/v2/docs/commands)
248
- - [Agents](https://opencode.ai/v2/docs/agents)
249
- - [Skills](https://opencode.ai/v2/docs/skills)
250
217
  - [AGENTS.md / instructions](https://opencode.ai/v2/docs/instructions)
251
218
  - [Plugin API reference](https://opencode.ai/v2/docs/api)
package/dist/index.js CHANGED
@@ -118,48 +118,9 @@ function projectAgentsBlock(systemName) {
118
118
 
119
119
  This repository has a framework-neutral Design System at [design-system/manifest.json](design-system/manifest.json). Before creating or changing UI, read [design-system/AI-GUIDELINES.md](design-system/AI-GUIDELINES.md) and discover the relevant tokens, components, and patterns through the manifest. Load only task-relevant documents; the structured Markdown and JSON files are authoritative, and [design-system/preview/index.html](design-system/preview/index.html) is generated visualization only.
120
120
 
121
- Honor explicit decisions in [design-system/preferences.json](design-system/preferences.json) and [design-system/DECISIONS.md](design-system/DECISIONS.md). Do not add arbitrary visual values or redesign existing identity during analysis. A screen brief is a design artifact in [design-system/screens/](design-system/screens/); implementation is a separate step. This guidance is intentionally tool- and framework-independent and applies even when the Design System plugin is unavailable.
121
+ Honor explicit decisions in [design-system/preferences.json](design-system/preferences.json) and [design-system/DECISIONS.md](design-system/DECISIONS.md). Do not add arbitrary visual values or redesign existing identity during analysis. A screen brief is a design artifact in [design-system/screens/](design-system/screens/); implementation is a separate step. This guidance is intentionally tool- and framework-independent: any coding agent can use the Design System without this plugin or project-local copies of plugin agents, commands, or skills.
122
122
  ${AGENTS_END}`;
123
123
  }
124
- var PORTABLE_SKILL = `---
125
- name: Design System
126
- description: Apply the project's design-system tokens, components, patterns, and accessibility guidance to UI design and implementation.
127
- ---
128
-
129
- Before any UI task:
130
-
131
- 1. Check whether design-system/manifest.json exists. If it does not, continue normally without inventing a system.
132
- 2. Read the manifest, AI-GUIDELINES.md, and preferences.json. Use manifest paths to discover relevant documents.
133
- 3. Load only tokens and component/pattern documents needed by this task. For a form, for example, load input/select/button plus the form pattern; do not read every component.
134
- 4. Treat explicit preferences and DECISIONS.md as user-owned constraints. Ask before changing a design identity decision; do not silently override it.
135
- 5. Use documented semantic tokens and components; preserve responsive, state, keyboard, focus, and accessibility requirements.
136
- 6. For design-only requests, write a screen brief to design-system/screens/<screen-name>.md and do not implement application code unless requested.
137
- 7. The preview is generated from structured tokens and specifications. Never use it as the only source of truth.
138
-
139
- For larger systems, read only the relevant paths discovered from the manifest and keep unrelated documentation out of context.
140
- `;
141
- var DESIGNER_AGENT = `---
142
- description: Collaborates with users to create and evolve original, accessible UI design systems.
143
- mode: subagent
144
- ---
145
-
146
- You are a senior UI/UX designer, accessibility specialist, and design-system architect. Collaborate in natural language. Start by understanding the product, audience, desired mood, references, explicit avoidances, platforms, and relevant accessibility needs. Ask only a few high-value questions when identity choices are unclear; offer concrete alternatives in everyday language. Do not turn the process into a long questionnaire, and do not decide identity questions on the user's behalf.
147
-
148
- Explicit preferences have priority. Record them structurally, repeat them into AI-GUIDELINES.md, and preserve them in every update. You may explain contrast or usability tradeoffs, but ask before departing from an explicit request. Build an original visual language rather than copying a known design system.
149
-
150
- For an existing application, use the read-only project analysis tool when available; otherwise inspect likely UI/style files without changing them. Preserve its recognizable identity by default. Distinguish probable accidents from intentional variants, explain evidence and uncertainty, and ask the user before normalizing ambiguous inconsistencies. Analysis never authorizes changing application files.
151
-
152
- When enough direction is known, summarize the proposed direction and ask for confirmation before committing a substantial initial system. Use Design System tools when available; otherwise create the documented Markdown/JSON files directly and use the included preview generator. Keep the system's status as draft/review until the user accepts it. Explain what changed and any unresolved choices.
153
- `;
154
- var SCREEN_AGENT = `---
155
- description: Produces implementation-ready screen specifications using the project's Design System.
156
- mode: subagent
157
- ---
158
-
159
- You are a UI/UX screen designer. Before designing, check design-system/manifest.json and follow AI-GUIDELINES.md. Load only the tokens, components, and patterns relevant to the requested screen. Understand the user's task, hierarchy, content, states, interactions, responsive behavior, and accessibility. Reuse the system; flag a missing reusable component rather than silently inventing a design language.
160
-
161
- Design is separate from code implementation. Produce a concise, implementation-ready Markdown specification with purpose, layout, hierarchy, components and token references, data/content, interactions and states, responsive behavior, and accessibility. Save it under design-system/screens/<kebab-case-name>.md using the screen-spec tool when available; otherwise write the Markdown file directly. Do not write React/Vue/etc. unless the user separately requests implementation. If no system exists, state that and create a coherent brief without claiming it follows a nonexistent system.
162
- `;
163
124
  function list(items) {
164
125
  return items?.length ? items.map((item) => `- ${item}`).join("\n") : "- None specified.";
165
126
  }
@@ -202,17 +163,6 @@ async function atomicWrite(root, relativePath, content) {
202
163
  throw error;
203
164
  }
204
165
  }
205
- async function writeIfAbsent(root, relativePath, content) {
206
- const destination = resolveInside(root, relativePath);
207
- await mkdir(path2.dirname(destination), { recursive: true });
208
- try {
209
- await writeFile(destination, content, { encoding: "utf8", flag: "wx" });
210
- return true;
211
- } catch (error) {
212
- if (error.code === "EEXIST") return false;
213
- throw error;
214
- }
215
- }
216
166
  async function updateManagedBlock(root, relativePath, startMarker, endMarker, block) {
217
167
  let current = "";
218
168
  try {
@@ -501,27 +451,8 @@ async function createDesignSystem(root, input) {
501
451
  await rm2(staging, { recursive: true, force: true }).catch(() => void 0);
502
452
  throw error;
503
453
  }
504
- const conflicts = [];
505
454
  await updateManagedBlock(root, "AGENTS.md", "<!-- opencode-design-system:start -->", "<!-- opencode-design-system:end -->", projectAgentsBlock(manifest.name));
506
- const supportFiles = [
507
- [".opencode/skills/design-system/SKILL.md", PORTABLE_SKILL],
508
- [".opencode/agents/design-system-designer.md", DESIGNER_AGENT],
509
- [".opencode/agents/screen-designer.md", SCREEN_AGENT],
510
- [".opencode/commands/design-system.md", `Create or continue the project's Design System. Treat the user as a collaborator: ask only relevant design identity questions, preserve explicit preferences, inspect existing UI read-only when appropriate, then create the framework-neutral files in design-system/. Read AGENTS.md and design-system/AI-GUIDELINES.md. If the OpenCode Design System tools are available, use them to validate and regenerate the preview. Do not edit application UI during analysis. User request: $ARGUMENTS
511
- `],
512
- [".opencode/commands/design-system/update.md", `Update the existing Design System in response to: $ARGUMENTS. Read its manifest, preferences, relevant tokens and component/pattern documents first. Explain affected parts and ask only if an identity choice is ambiguous. Keep the user's explicit preferences. Apply semantic updates, record the decision, update the version/changelog, run consistency checks, and regenerate the preview from tokens/specifications. If plugin tools are not available, edit the structured Markdown/JSON deliberately and run node design-system/tools/generate-preview.mjs. Do not use blind search/replace and do not modify application components unless explicitly asked.
513
- `],
514
- [".opencode/commands/design-system/preview.md", `Regenerate design-system/preview/index.html from manifest.json, tokens.json, component documents, and patterns. Treat structured Markdown/JSON as the source of truth. If the Design System plugin is available, use its preview tool; otherwise run node design-system/tools/generate-preview.mjs from the project root.
515
- `],
516
- [".opencode/commands/design-system/check.md", `Check project UI code against design-system/manifest.json and its semantic tokens. Report unknown values, component/state/layout deviations, and likely inconsistencies with file paths. Do not edit application code. If available, use the Design System check tool.
517
- `],
518
- [".opencode/commands/design-screen.md", `Design (do not implement) the requested screen using the Design System. Read AGENTS.md and design-system/AI-GUIDELINES.md, then load only the matching manifest entries, tokens, components, and patterns. Write an implementation-ready brief to design-system/screens/<kebab-case-name>.md with purpose, layout, hierarchy, components/token references, content/data, interactions/states, responsive behavior, and accessibility. If the Design System is absent, say so and write a portable brief without claiming system conformance. Request: $ARGUMENTS
519
- `]
520
- ];
521
- for (const [relative, content] of supportFiles) {
522
- if (!await writeIfAbsent(root, relative, content)) conflicts.push(relative);
523
- }
524
- return { success: true, manifest, files: [...files.keys()].map((file) => `${DESIGN_SYSTEM_DIR}/${file}`), conflicts };
455
+ return { success: true, manifest, files: [...files.keys()].map((file) => `${DESIGN_SYSTEM_DIR}/${file}`) };
525
456
  }
526
457
  async function regeneratePreview(root) {
527
458
  const manifest = await readManifest(root);
@@ -615,7 +546,7 @@ Read the manifest and AI guidelines first. Load only task-relevant component and
615
546
 
616
547
  ## Plugin-independent maintenance
617
548
 
618
- This project includes [tools/generate-preview.mjs](tools/generate-preview.mjs), a dependency-free Node.js renderer. After editing structured tokens/specifications without the plugin, run node design-system/tools/generate-preview.mjs from the project root. The project [AGENTS.md](../AGENTS.md) and local OpenCode Skill/agents/commands preserve usage guidance when the plugin is not installed.
549
+ This project includes [tools/generate-preview.mjs](tools/generate-preview.mjs), a dependency-free Node.js renderer. After editing structured tokens/specifications without the plugin, run node design-system/tools/generate-preview.mjs from the project root. The project's [AGENTS.md](../AGENTS.md) block points any coding agent to the portable system; no project-local plugin agents, commands, or skills are required.
619
550
  `;
620
551
  }
621
552
  function pretty(value) {
@@ -1211,14 +1142,14 @@ var commandPrompts = [
1211
1142
  {
1212
1143
  name: "design-system",
1213
1144
  description: "Create a Design System collaboratively, from scratch or from an existing UI",
1214
- instruction: `Act as the project's design-system-designer. Collaborate naturally and gather only the identity decisions that are genuinely unclear. Explicit preferences always win. If a Design System already exists, read it and offer an update/continue path rather than overwriting it. If the repository has UI and the user has not said whether to formalize that UI or start fresh, call the read-only analysis tool and ask them which path they prefer; do not assume. Distinguish evidence from inference and ask about important inconsistencies before normalization. For a new system, confirm a concise visual direction before writing files; then call design_system_create with neutral tokens, foundations, explicit preferences, a few useful components and patterns, and any source evidence. Keep status draft until reviewed. Do not modify application files.
1145
+ instruction: `Act as a collaborative design-system designer. Gather only identity decisions that are genuinely unclear; honor explicit preferences. If a Design System already exists, read it and offer an update/continue path rather than overwriting it. If the repository has UI and the user has not said whether to formalize that UI or start fresh, call the read-only analysis tool and ask which path they prefer; do not assume. Distinguish evidence from inference and ask about important inconsistencies before normalization. For a new system, confirm a concise visual direction before writing files; then call design_system_create with neutral tokens, foundations, explicit preferences, a few useful components and patterns, and source evidence. Keep status draft until reviewed. Do not modify application files.
1215
1146
 
1216
1147
  User request:`
1217
1148
  },
1218
1149
  {
1219
1150
  name: "design-system/update",
1220
1151
  description: "Make a coherent, versioned change to the existing Design System",
1221
- instruction: `Read the Design System first using design_system_read. When the design-system-designer subagent is available, delegate the design decision to it; otherwise adopt its collaborative role. Interpret the user's request semantically, identify impacted token paths and dependent components/patterns, and honor recorded decisions. If the request conflicts with an explicit preference, ask before changing that preference. For a clear requested change, apply it with design_system_update, explain the dependency impact, provide revised full componentUpdates/patternUpdates where documented behavior or guidance needs a semantic change, add tokens only when existing semantic paths do not fit and then provide a value for every theme, add reusable components/patterns when composition is insufficient, update preferences/decisions/foundations where appropriate, choose patch/minor/major impact (expansion requires at least minor), and report any unresolved references. Do not use blind text replacement and do not modify app UI code.
1152
+ instruction: `Work collaboratively as a design-system architect. Read the Design System first using design_system_read. Interpret the request semantically, identify impacted token paths and dependent components/patterns, and honor recorded decisions. If the request conflicts with an explicit preference, ask before changing it. For a clear requested change, apply it with design_system_update, explain the dependency impact, provide revised full componentUpdates/patternUpdates where documented behavior or guidance needs a semantic change, add tokens only when existing semantic paths do not fit and then provide a value for every theme, add reusable components/patterns when composition is insufficient, update preferences/decisions/foundations where appropriate, choose patch/minor/major impact (expansion requires at least minor), and report unresolved references. Do not use blind text replacement and do not modify app UI code.
1222
1153
 
1223
1154
  User request:`
1224
1155
  },
@@ -1239,7 +1170,7 @@ User request:`
1239
1170
  {
1240
1171
  name: "design-screen",
1241
1172
  description: "Design a screen specification using relevant Design System documentation",
1242
- instruction: `Use the screen-designer subagent when available; otherwise adopt its system prompt. First call design_system_read with the user's task to load only the relevant tokens, components, patterns, preferences, and system guidelines. Design and document hierarchy, content, layout, states, interactions, responsive behavior, and accessibility. Keep design separate from implementation. Call design_system_screen_spec to save an implementation-ready Markdown specification under design-system/screens/. Do not write UI code unless asked separately.
1173
+ instruction: `Act as a UI/UX screen designer. First call design_system_read with the user's task to load only the relevant tokens, components, patterns, preferences, and guidelines. Clarify the screen's purpose and key content when needed, then define hierarchy, layout, data, states, interactions, responsive behavior, and accessibility. Keep design separate from implementation. Call design_system_screen_spec to save an implementation-ready Markdown specification under design-system/screens/. Do not write UI code unless asked separately.
1243
1174
 
1244
1175
  User request:`
1245
1176
  }
@@ -1249,22 +1180,11 @@ var index_default = Plugin.define({
1249
1180
  async setup(ctx) {
1250
1181
  const projectRoot = path5.resolve(ctx.location.project.canonical || ctx.location.directory);
1251
1182
  const designSystemPath = path5.join(projectRoot, DESIGN_SYSTEM_DIR, "manifest.json");
1252
- const skillPath = path5.join(projectRoot, ".opencode", "skills", "design-system", "SKILL.md");
1253
- await ctx.skill.transform((editor) => {
1254
- editor.add({
1255
- id: "design-system",
1256
- name: "Design System",
1257
- description: "Apply this project's semantic design tokens, documented components, patterns, preferences, and accessibility guidance to UI work with progressive loading.",
1258
- path: skillPath,
1259
- content: skillBody(),
1260
- autoinvoke: true
1261
- });
1262
- });
1263
1183
  await ctx.session.hook("context", (event) => {
1264
1184
  if (!existsSync(designSystemPath)) return;
1265
1185
  event.system.push({
1266
1186
  type: "text",
1267
- text: "This project has a portable design-system/manifest.json. For UI tasks, load the design-system skill and read only the relevant token/component/pattern files. Honor AI-GUIDELINES.md, preferences.json, and DECISIONS.md. The HTML preview is generated output, not the source of truth."
1187
+ text: "This project has a framework-neutral Design System at design-system/manifest.json. Follow the Design System guidance in AGENTS.md and design-system/AI-GUIDELINES.md; read only the relevant tokens, components, and patterns, and treat the HTML preview as generated output rather than the source of truth."
1268
1188
  });
1269
1189
  });
1270
1190
  await ctx.command.transform((editor) => {
@@ -1314,7 +1234,6 @@ ${prompt.text.trim()}` : "";
1314
1234
  },
1315
1235
  execute: async (raw) => {
1316
1236
  const result = await createDesignSystem(projectRoot, raw);
1317
- await ctx.skill.reload();
1318
1237
  return { content: JSON.stringify(result, null, 2) };
1319
1238
  }
1320
1239
  });
@@ -1443,9 +1362,6 @@ var patternSchema = {
1443
1362
  function stringArray() {
1444
1363
  return { type: "array", items: { type: "string" } };
1445
1364
  }
1446
- function skillBody() {
1447
- return PORTABLE_SKILL.replace(/^---\n[\s\S]*?\n---\n\n/, "");
1448
- }
1449
1365
  async function readRelevantSystem(root, task) {
1450
1366
  try {
1451
1367
  const manifest = await readManifest(root);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "opencode-design-system",
3
- "version": "0.1.0",
3
+ "version": "1.0.1",
4
4
  "description": "An OpenCode v2 plugin for creating, evolving, previewing, and using portable AI-readable design systems.",
5
5
  "repository": {
6
6
  "type": "git",