opencode-design-system 1.0.1 → 1.0.2
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.
- package/README.es.md +244 -0
- package/README.md +125 -99
- package/README.pt-BR.md +244 -0
- package/dist/index.js +205 -50
- package/package.json +3 -1
- package/templates/generate-preview.mjs +38 -68
- package/templates/preview-renderer.d.mts +33 -0
- package/templates/preview-renderer.mjs +199 -0
package/README.es.md
ADDED
|
@@ -0,0 +1,244 @@
|
|
|
1
|
+
# OpenCode Design System
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/opencode-design-system)
|
|
4
|
+
[](https://github.com/BraveOtter/opencode-design-system/blob/main/LICENSE)
|
|
5
|
+
[](https://opencode.ai/v2/docs/)
|
|
6
|
+
|
|
7
|
+
**Un plugin colaborativo de OpenCode v2 para crear y evolucionar sistemas de diseño portables y neutrales respecto al framework, que los agentes de IA puedan seguir de verdad.**
|
|
8
|
+
|
|
9
|
+
[English](https://github.com/BraveOtter/opencode-design-system/blob/main/README.md) · [Español](https://github.com/BraveOtter/opencode-design-system/blob/main/README.es.md) · [Português (Brasil)](https://github.com/BraveOtter/opencode-design-system/blob/main/README.pt-BR.md)
|
|
10
|
+
|
|
11
|
+
El sistema de diseño se convierte en la memoria visual duradera del proyecto: **Markdown y JSON** estructurados para tokens semánticos, preferencias explícitas, decisiones de diseño, componentes, patrones y especificaciones de pantallas. Se genera una vista HTML interactiva a partir de esas fuentes; nunca es una segunda fuente de verdad.
|
|
12
|
+
|
|
13
|
+
## ¿Por qué este plugin?
|
|
14
|
+
|
|
15
|
+
- **Empieza con una conversación, no con un cuestionario.** Aclara solo las decisiones importantes de identidad que aún no estén definidas y conserva explícitas las preferencias del usuario.
|
|
16
|
+
- **Documenta lo que ya existe.** Un análisis acotado y de solo lectura ayuda a formalizar una interfaz existente sin rediseñarla silenciosamente.
|
|
17
|
+
- **Entrega a los agentes el contexto pertinente.** La carga progresiva proporciona los tokens, componentes, patrones y pautas relevantes para cada tarea de UI, en vez de volcar todo el sistema en cada prompt.
|
|
18
|
+
- **Evoluciona el sistema con coherencia.** Registra decisiones, dependencias de tokens semánticos, componentes y patrones afectados, estado y versiones del sistema de diseño.
|
|
19
|
+
- **Evita depender de un framework.** El formato autoritativo es Markdown y JSON, no React, Vue, Tailwind ni una vista generada.
|
|
20
|
+
- **Protege los archivos del proyecto.** El análisis y las comprobaciones son de solo lectura. La creación no reemplaza un directorio `design-system/` existente y conserva el contenido de `AGENTS.md` fuera del bloque administrado por el plugin.
|
|
21
|
+
|
|
22
|
+
## Requisitos
|
|
23
|
+
|
|
24
|
+
- [OpenCode v2](https://opencode.ai/v2/docs/)
|
|
25
|
+
- Node.js **22.19 o posterior**
|
|
26
|
+
|
|
27
|
+
## Instalación
|
|
28
|
+
|
|
29
|
+
### Instalar el paquete publicado en npm
|
|
30
|
+
|
|
31
|
+
Instálalo globalmente con la CLI de OpenCode:
|
|
32
|
+
|
|
33
|
+
```sh
|
|
34
|
+
opencode plugin add opencode-design-system
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Para fijar una versión concreta de npm, sustituye `<version>` por la versión deseada:
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
opencode plugin add opencode-design-system@<version>
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
O configúralo para un proyecto en `opencode.json` o `opencode.jsonc`:
|
|
44
|
+
|
|
45
|
+
```jsonc
|
|
46
|
+
{
|
|
47
|
+
"$schema": "https://opencode.ai/config.json",
|
|
48
|
+
"plugins": ["opencode-design-system"]
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
OpenCode carga los plugins configurados al iniciar. Si no aparece, reinicia OpenCode o el servicio de OpenCode.
|
|
53
|
+
|
|
54
|
+
### Instalar directamente desde GitHub
|
|
55
|
+
|
|
56
|
+
Para instalar la versión más reciente de la rama predeterminada:
|
|
57
|
+
|
|
58
|
+
```sh
|
|
59
|
+
opencode plugin add github:BraveOtter/opencode-design-system
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Para fijar una versión etiquetada de GitHub, sustituye `<tag>` por el tag deseado:
|
|
63
|
+
|
|
64
|
+
```sh
|
|
65
|
+
opencode plugin add github:BraveOtter/opencode-design-system#<tag>
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### Usar un checkout local
|
|
69
|
+
|
|
70
|
+
Clona el repositorio, instala las dependencias de desarrollo y compílalo:
|
|
71
|
+
|
|
72
|
+
```sh
|
|
73
|
+
npm install
|
|
74
|
+
npm run build
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Después, indica a OpenCode la ruta del checkout (ajusta la ruta relativa a tu proyecto):
|
|
78
|
+
|
|
79
|
+
```jsonc
|
|
80
|
+
{
|
|
81
|
+
"$schema": "https://opencode.ai/config.json",
|
|
82
|
+
"plugins": ["../opencode-design-system"]
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
El repositorio también incluye un entrypoint local opcional para pruebas en `plugins/local/index.js`; no se carga automáticamente ni forma parte del paquete npm.
|
|
87
|
+
|
|
88
|
+
## Primeros pasos
|
|
89
|
+
|
|
90
|
+
Crea un sistema a partir de una dirección visual:
|
|
91
|
+
|
|
92
|
+
```text
|
|
93
|
+
/design-system Un espacio de trabajo sereno y compacto, con verdes apagados, superficies nítidas y sin degradados.
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Si el proyecto ya tiene una interfaz, pide al agente que la analice primero. Explicará lo que encontró y preguntará si quieres documentar la identidad visual existente o empezar desde cero antes de crear archivos:
|
|
97
|
+
|
|
98
|
+
```text
|
|
99
|
+
/design-system Analiza la interfaz de esta aplicación y ayúdame a documentar su lenguaje visual actual.
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Para diseñar una pantalla sin pedir al plugin que implemente código de UI:
|
|
103
|
+
|
|
104
|
+
```text
|
|
105
|
+
/design-screen Administración de usuarios con búsqueda, filtros, invitaciones y estados vacíos.
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
También puedes pedir una especificación de pantalla en lenguaje natural sin usar `/design-screen`. Cuando existe un manifest, el plugin remite al agente a `AGENTS.md` y a las pautas pertinentes del sistema.
|
|
109
|
+
|
|
110
|
+
## Comandos
|
|
111
|
+
|
|
112
|
+
| Comando | Función |
|
|
113
|
+
| --- | --- |
|
|
114
|
+
| `/design-system [idea]` | Crear un sistema en colaboración o conversar sobre cómo documentar una interfaz existente. |
|
|
115
|
+
| `/design-system/update [cambio]` | Aplicar un cambio semántico versionado e identificar la documentación dependiente. |
|
|
116
|
+
| `/design-system/preview` | Regenerar la vista interactiva a partir de los archivos estructurados. |
|
|
117
|
+
| `/design-system/check` | Comprobación heurística de solo lectura para detectar posibles diferencias entre estilos y tokens documentados. |
|
|
118
|
+
| `/design-screen [pantalla]` | Guardar una especificación lista para implementar, sin escribir código de UI de la aplicación. |
|
|
119
|
+
|
|
120
|
+
El plugin también registra las herramientas `design_system_create`, `design_system_read`, `design_system_analyze`, `design_system_update`, `design_system_preview`, `design_system_check` y `design_system_screen_spec` para que el agente las use cuando lo necesite.
|
|
121
|
+
|
|
122
|
+
## Cómo funciona
|
|
123
|
+
|
|
124
|
+
### Un flujo cuidadoso para productos existentes
|
|
125
|
+
|
|
126
|
+
La herramienta `design_system_analyze` lee posibles fuentes de UI y estilos, configuraciones reconocidas de frameworks y dependencias declaradas. Resume evidencias como variables CSS, colores, radios, espaciado, breakpoints responsive y componentes candidatos. El análisis tiene límites, omite directorios de dependencias y compilación, no sigue enlaces simbólicos y no modifica los archivos que lee. Los resultados son indicios, no una prueba de que una diferencia sea un error.
|
|
127
|
+
|
|
128
|
+
El agente explica las incertidumbres y pregunta antes de normalizar decisiones visuales importantes o ambiguas. Analizar no significa que tenga permiso para rediseñar ni modificar el código de la aplicación.
|
|
129
|
+
|
|
130
|
+
### Protección de los archivos del proyecto
|
|
131
|
+
|
|
132
|
+
Crear un sistema escribe un nuevo directorio `design-system/` y añade o actualiza únicamente el bloque administrado por el plugin en el `AGENTS.md` raíz. Si `design-system/` ya contiene archivos, la creación no los reemplaza. Las actualizaciones escriben deliberadamente en los artefactos del sistema; las herramientas integradas de análisis y comprobación nunca editan archivos de UI de la aplicación.
|
|
133
|
+
|
|
134
|
+
Las instrucciones administradas de `AGENTS.md` son portables: indican a OpenCode y a otros agentes cómo encontrar las fuentes neutrales al framework y cargar solo lo necesario para cada tarea. El plugin no copia agentes, comandos ni skills al proyecto.
|
|
135
|
+
|
|
136
|
+
### Una fuente de verdad portable
|
|
137
|
+
|
|
138
|
+
El directorio generado suele tener esta estructura:
|
|
139
|
+
|
|
140
|
+
```text
|
|
141
|
+
design-system/
|
|
142
|
+
├── README.md
|
|
143
|
+
├── manifest.json
|
|
144
|
+
├── tokens.json
|
|
145
|
+
├── preferences.json
|
|
146
|
+
├── FOUNDATIONS.md
|
|
147
|
+
├── AI-GUIDELINES.md
|
|
148
|
+
├── DECISIONS.md
|
|
149
|
+
├── CHANGELOG.md
|
|
150
|
+
├── schema/
|
|
151
|
+
├── components/
|
|
152
|
+
├── patterns/
|
|
153
|
+
├── screens/
|
|
154
|
+
├── preview/
|
|
155
|
+
│ └── index.html
|
|
156
|
+
└── tools/
|
|
157
|
+
└── generate-preview.mjs
|
|
158
|
+
|
|
159
|
+
AGENTS.md # El contenido existente se conserva fuera del bloque administrado.
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
El manifest indexa temas, versiones, archivos y las referencias a tokens declaradas por cada componente y patrón. Los sistemas empiezan en `0.1.0` con la versión de esquema `1.0.0`; su estado puede ser `draft`, `review` o `stable`.
|
|
163
|
+
|
|
164
|
+
Los tokens usan rutas semánticas y pueden definir varios temas:
|
|
165
|
+
|
|
166
|
+
```json
|
|
167
|
+
{
|
|
168
|
+
"$schema": "./schema/tokens.schema.json",
|
|
169
|
+
"schemaVersion": "1.0.0",
|
|
170
|
+
"themes": {
|
|
171
|
+
"light": {
|
|
172
|
+
"color": {
|
|
173
|
+
"surface": { "base": "#f6f8f7", "raised": "#ffffff" },
|
|
174
|
+
"text": { "primary": "#17211f", "secondary": "#65726d" },
|
|
175
|
+
"accent": { "primary": "#276f55" }
|
|
176
|
+
},
|
|
177
|
+
"radius": { "control": "6px", "card": "8px" },
|
|
178
|
+
"spacing": { "sm": "8px", "md": "16px" }
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
El vocabulario puede ampliarse para incluir tipografía, layout, elevación, movimiento, breakpoints, foco y estados. Los componentes describen propósito, variantes, tokens, comportamiento, accesibilidad, adaptación responsive y relaciones. Los patrones documentan composiciones útiles, como formularios, navegación, filtros, tablas y estados vacíos.
|
|
185
|
+
|
|
186
|
+
### Actualizaciones significativas y versionadas
|
|
187
|
+
|
|
188
|
+
`/design-system/update` lee el manifest y los documentos pertinentes antes de cambiar el sistema. Por defecto, una actualización de token semántico aplica esa ruta a todos los temas; usa el prefijo `themes.<name>.` para modificar solo uno. La actualización registra el motivo, encuentra los dependientes declarados, actualiza la documentación pertinente y regenera la vista previa.
|
|
189
|
+
|
|
190
|
+
El impacto en la versión del sistema de diseño sigue estas reglas:
|
|
191
|
+
|
|
192
|
+
- **PATCH**: correcciones compatibles o cambios de documentación.
|
|
193
|
+
- **MINOR**: nuevas adiciones compatibles, como un token, componente o patrón.
|
|
194
|
+
- **MAJOR**: cambios que pueden romper contratos de diseño existentes.
|
|
195
|
+
|
|
196
|
+
Estas versiones corresponden al sistema de diseño generado en el proyecto, no al paquete npm del plugin. De forma predeterminada, los sistemas actualizados vuelven a `draft` para que una persona pueda revisarlos.
|
|
197
|
+
|
|
198
|
+
## Vista interactiva
|
|
199
|
+
|
|
200
|
+
`design-system/preview/index.html` se genera a partir del manifest, los tokens y las especificaciones de componentes y patrones. Incluye muestras de tokens, ejemplos de componentes, cambio de tema cuando hay varios y ejemplos interactivos. Respeta el foco visible por teclado y `prefers-reduced-motion`.
|
|
201
|
+
|
|
202
|
+
Regénérala en OpenCode con `/design-system/preview` o, sin el plugin, desde la raíz del proyecto:
|
|
203
|
+
|
|
204
|
+
```sh
|
|
205
|
+
node design-system/tools/generate-preview.mjs
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
El renderer independiente no tiene dependencias externas. Edita los archivos estructurados Markdown y JSON, no el HTML generado, para cambiar el sistema.
|
|
209
|
+
|
|
210
|
+
## Desarrollo y pruebas
|
|
211
|
+
|
|
212
|
+
```sh
|
|
213
|
+
npm install
|
|
214
|
+
npm run typecheck
|
|
215
|
+
npm test
|
|
216
|
+
npm run build
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
Las pruebas cubren un flujo integrado en un proyecto temporal: análisis de solo lectura, creación y conservación de archivos del usuario, actualización del bloque administrado de `AGENTS.md`, especificaciones de pantallas, cambios de tokens entre temas, vistas previas, comprobaciones y seguridad de rutas.
|
|
220
|
+
|
|
221
|
+
## Publicar una versión
|
|
222
|
+
|
|
223
|
+
El workflow de GitHub Actions `Publish to npm` publica al subir un tag `vX.Y.Z`, una vez superadas las comprobaciones y verificado que el tag coincide con la versión de `package.json`. Antes de la primera publicación, configura Trusted Publishing en npm para el repositorio `BraveOtter/opencode-design-system` y el workflow `publish.yml`, y permite la acción directa `npm publish`. El workflow usa OIDC, así que no hace falta guardar un token de publicación de npm en GitHub; además, npm genera automáticamente la atestación de procedencia para este repositorio público.
|
|
224
|
+
|
|
225
|
+
Para actualizar la versión del paquete y subir su commit y tag:
|
|
226
|
+
|
|
227
|
+
```sh
|
|
228
|
+
npm version patch # o minor / major
|
|
229
|
+
git push --follow-tags
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
## Documentación
|
|
233
|
+
|
|
234
|
+
- [Guía de plugins de OpenCode v2](https://opencode.ai/v2/docs/build/plugins)
|
|
235
|
+
- [Configuración de plugins de OpenCode](https://opencode.ai/v2/docs/plugins)
|
|
236
|
+
- [Comandos de OpenCode](https://opencode.ai/v2/docs/commands)
|
|
237
|
+
- [Instrucciones de OpenCode y `AGENTS.md`](https://opencode.ai/v2/docs/instructions)
|
|
238
|
+
- [Referencia de la API de plugins](https://opencode.ai/v2/docs/api)
|
|
239
|
+
- [Paquete npm](https://www.npmjs.com/package/opencode-design-system)
|
|
240
|
+
- [Reportar un problema](https://github.com/BraveOtter/opencode-design-system/issues)
|
|
241
|
+
|
|
242
|
+
## Licencia
|
|
243
|
+
|
|
244
|
+
Este proyecto está publicado bajo la [Licencia MIT](https://github.com/BraveOtter/opencode-design-system/blob/main/LICENSE).
|
package/README.md
CHANGED
|
@@ -1,24 +1,46 @@
|
|
|
1
1
|
# OpenCode Design System
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/opencode-design-system)
|
|
4
|
+
[](https://github.com/BraveOtter/opencode-design-system/blob/main/LICENSE)
|
|
5
|
+
[](https://opencode.ai/v2/docs/)
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
**A collaborative OpenCode v2 plugin for creating and evolving portable, framework-neutral design systems that AI agents can actually follow.**
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
[English](https://github.com/BraveOtter/opencode-design-system/blob/main/README.md) · [Español](https://github.com/BraveOtter/opencode-design-system/blob/main/README.es.md) · [Português (Brasil)](https://github.com/BraveOtter/opencode-design-system/blob/main/README.pt-BR.md)
|
|
8
10
|
|
|
9
|
-
|
|
11
|
+
The design system becomes a project's durable visual memory: structured **Markdown and JSON** for semantic tokens, explicit preferences, design decisions, components, patterns, and screen briefs. A live HTML preview is generated from those sources; it is never a second source of truth.
|
|
10
12
|
|
|
11
|
-
|
|
13
|
+
## Why this plugin?
|
|
14
|
+
|
|
15
|
+
- **Start from a conversation, not a questionnaire.** Resolve only the important identity choices that are still unclear, and keep the user's preferences explicit.
|
|
16
|
+
- **Document what already exists.** Bounded, read-only analysis can help formalize an existing UI without silently redesigning it.
|
|
17
|
+
- **Give agents the relevant context.** Progressive loading supplies the tokens, components, patterns, and guidance relevant to a UI task instead of dumping the whole system into every prompt.
|
|
18
|
+
- **Evolve the system coherently.** Track decisions, semantic token dependencies, affected components and patterns, status, and design-system version changes.
|
|
19
|
+
- **Avoid framework lock-in.** The authoritative format is Markdown and JSON, not React, Vue, Tailwind, or a generated preview.
|
|
20
|
+
- **Keep project files safe.** Analysis and checks are read-only. Design-system creation refuses to replace an existing `design-system/` directory, and existing `AGENTS.md` content outside the plugin-managed block is preserved.
|
|
21
|
+
|
|
22
|
+
## Requirements
|
|
23
|
+
|
|
24
|
+
- [OpenCode v2](https://opencode.ai/v2/docs/)
|
|
25
|
+
- Node.js **22.19 or newer**
|
|
26
|
+
|
|
27
|
+
## Install
|
|
28
|
+
|
|
29
|
+
### Install the published npm package
|
|
30
|
+
|
|
31
|
+
Install it globally with the OpenCode CLI:
|
|
12
32
|
|
|
13
33
|
```sh
|
|
14
|
-
opencode plugin add
|
|
34
|
+
opencode plugin add opencode-design-system
|
|
15
35
|
```
|
|
16
36
|
|
|
17
|
-
|
|
37
|
+
To pin a specific npm release, replace `<version>` with the version you want:
|
|
18
38
|
|
|
19
|
-
|
|
39
|
+
```sh
|
|
40
|
+
opencode plugin add opencode-design-system@<version>
|
|
41
|
+
```
|
|
20
42
|
|
|
21
|
-
|
|
43
|
+
Or configure it for a project in `opencode.json` or `opencode.jsonc`:
|
|
22
44
|
|
|
23
45
|
```jsonc
|
|
24
46
|
{
|
|
@@ -27,72 +49,93 @@ Añade el paquete a `plugins` en `opencode.json` o `opencode.jsonc`:
|
|
|
27
49
|
}
|
|
28
50
|
```
|
|
29
51
|
|
|
30
|
-
OpenCode
|
|
52
|
+
OpenCode loads configured plugins at startup. If the plugin does not appear, restart OpenCode or the OpenCode service.
|
|
53
|
+
|
|
54
|
+
### Install directly from GitHub
|
|
55
|
+
|
|
56
|
+
For the repository's latest default-branch version:
|
|
31
57
|
|
|
32
|
-
|
|
58
|
+
```sh
|
|
59
|
+
opencode plugin add github:BraveOtter/opencode-design-system
|
|
60
|
+
```
|
|
33
61
|
|
|
34
|
-
|
|
62
|
+
To pin a tagged GitHub release, replace `<tag>` with the tag you want:
|
|
63
|
+
|
|
64
|
+
```sh
|
|
65
|
+
opencode plugin add github:BraveOtter/opencode-design-system#<tag>
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### Use a local checkout
|
|
69
|
+
|
|
70
|
+
Clone the repository, install its development dependencies, and build it:
|
|
35
71
|
|
|
36
72
|
```sh
|
|
37
73
|
npm install
|
|
38
74
|
npm run build
|
|
39
75
|
```
|
|
40
76
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
Apunta OpenCode al directorio del paquete:
|
|
77
|
+
Then point OpenCode to the checkout directory (adjust the relative path to your project):
|
|
44
78
|
|
|
45
79
|
```jsonc
|
|
46
80
|
{
|
|
47
81
|
"$schema": "https://opencode.ai/config.json",
|
|
48
|
-
"plugins": ["
|
|
82
|
+
"plugins": ["../opencode-design-system"]
|
|
49
83
|
}
|
|
50
84
|
```
|
|
51
85
|
|
|
52
|
-
|
|
86
|
+
The repository also contains an optional local test entry point at `plugins/local/index.js`; it is not loaded automatically and is not part of the npm package.
|
|
53
87
|
|
|
54
|
-
##
|
|
88
|
+
## Get started
|
|
55
89
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
| `/design-system/check` | Inspección heurística y de solo lectura de estilos frente a los tokens. |
|
|
62
|
-
| `/design-screen [pantalla]` | Diseñar y guardar una especificación de pantalla sin implementar código UI. |
|
|
90
|
+
Create a system from a visual direction:
|
|
91
|
+
|
|
92
|
+
```text
|
|
93
|
+
/design-system A calm, compact workspace with muted greens, crisp surfaces, and no gradients.
|
|
94
|
+
```
|
|
63
95
|
|
|
64
|
-
|
|
96
|
+
If the project already has a UI, ask the agent to inspect it first. It will explain what it found and ask whether you want to document the existing identity or start fresh before creating anything:
|
|
65
97
|
|
|
66
98
|
```text
|
|
67
|
-
/design-system
|
|
68
|
-
/design-system/update Los botones y las cards se ven demasiado redondeados.
|
|
69
|
-
/design-screen Administración de usuarios con búsqueda, filtros e invitaciones.
|
|
99
|
+
/design-system Analyze this app's UI and help me document its existing visual language.
|
|
70
100
|
```
|
|
71
101
|
|
|
72
|
-
|
|
102
|
+
To design a screen without asking the plugin to implement UI code:
|
|
73
103
|
|
|
74
|
-
|
|
104
|
+
```text
|
|
105
|
+
/design-screen User management with search, filters, invitations, and empty states.
|
|
106
|
+
```
|
|
75
107
|
|
|
76
|
-
|
|
108
|
+
You can also request a screen brief in natural language without invoking `/design-screen`. When a manifest exists, the plugin points the agent to the project's `AGENTS.md` and relevant design-system guidance.
|
|
77
109
|
|
|
78
|
-
|
|
110
|
+
## Commands
|
|
111
|
+
|
|
112
|
+
| Command | What it does |
|
|
113
|
+
| --- | --- |
|
|
114
|
+
| `/design-system [idea]` | Collaboratively create a system from scratch or discuss documenting an existing UI. |
|
|
115
|
+
| `/design-system/update [change]` | Apply a semantic, versioned change and identify dependent documentation. |
|
|
116
|
+
| `/design-system/preview` | Regenerate the interactive preview from the structured files. |
|
|
117
|
+
| `/design-system/check` | Run a read-only, heuristic check for UI styles that may drift from documented tokens. |
|
|
118
|
+
| `/design-screen [screen]` | Save an implementation-ready screen brief without writing application UI code. |
|
|
119
|
+
|
|
120
|
+
The plugin also registers `design_system_create`, `design_system_read`, `design_system_analyze`, `design_system_update`, `design_system_preview`, `design_system_check`, and `design_system_screen_spec` tools for the agent to use as needed.
|
|
79
121
|
|
|
80
|
-
##
|
|
122
|
+
## How it works
|
|
81
123
|
|
|
82
|
-
|
|
124
|
+
### A careful workflow for existing products
|
|
83
125
|
|
|
84
|
-
|
|
85
|
-
- `ctx.command.transform` para commands.
|
|
86
|
-
- `ctx.tool.transform` para herramientas de creación, lectura progresiva, análisis, actualización, preview, comprobación y especificaciones de pantalla.
|
|
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.
|
|
126
|
+
The `design_system_analyze` tool reads likely UI and style sources, recognized framework configuration, and declared dependencies. It summarizes evidence such as CSS variables, colors, radii, spacing, responsive breakpoints, and component candidates. The scan is bounded, skips dependency/build directories and symlinks, and does not modify the files it reads. Findings are clues—not proof that a difference is a mistake.
|
|
88
127
|
|
|
89
|
-
|
|
128
|
+
The agent explains uncertainty and asks before normalizing important or ambiguous visual decisions. Analysis is not permission to redesign or edit application code.
|
|
90
129
|
|
|
91
|
-
###
|
|
130
|
+
### Safe project ownership
|
|
92
131
|
|
|
93
|
-
|
|
132
|
+
Creating a system writes a new `design-system/` directory and adds or updates only the plugin-managed block in the root `AGENTS.md`. If `design-system/` already contains files, creation refuses to replace them. Updates are deliberate writes to design-system artifacts; the plugin's built-in analysis and check tools never edit application UI files.
|
|
94
133
|
|
|
95
|
-
|
|
134
|
+
The managed `AGENTS.md` guidance is portable: it tells OpenCode and other coding agents how to find the framework-neutral sources and load only what a task needs. The plugin does not copy agents, commands, or skills into the project.
|
|
135
|
+
|
|
136
|
+
### A portable source of truth
|
|
137
|
+
|
|
138
|
+
The generated directory typically looks like this:
|
|
96
139
|
|
|
97
140
|
```text
|
|
98
141
|
design-system/
|
|
@@ -105,27 +148,20 @@ design-system/
|
|
|
105
148
|
├── DECISIONS.md
|
|
106
149
|
├── CHANGELOG.md
|
|
107
150
|
├── schema/
|
|
108
|
-
│ ├── manifest.schema.json
|
|
109
|
-
│ └── tokens.schema.json
|
|
110
151
|
├── components/
|
|
111
|
-
│ ├── button.md
|
|
112
|
-
│ └── ...
|
|
113
152
|
├── patterns/
|
|
114
|
-
│ ├── form.md
|
|
115
|
-
│ └── ...
|
|
116
153
|
├── screens/
|
|
117
|
-
│ └── user-management.md
|
|
118
154
|
├── preview/
|
|
119
155
|
│ └── index.html
|
|
120
156
|
└── tools/
|
|
121
157
|
└── generate-preview.mjs
|
|
122
158
|
|
|
123
|
-
AGENTS.md
|
|
159
|
+
AGENTS.md # Existing content is kept outside the managed block.
|
|
124
160
|
```
|
|
125
161
|
|
|
126
|
-
|
|
162
|
+
The manifest indexes themes, versions, files, and the token references declared by each component and pattern. Systems begin at `0.1.0` with schema version `1.0.0`; their review status is `draft`, `review`, or `stable`.
|
|
127
163
|
|
|
128
|
-
|
|
164
|
+
Tokens use semantic paths and can define multiple themes:
|
|
129
165
|
|
|
130
166
|
```json
|
|
131
167
|
{
|
|
@@ -145,61 +181,33 @@ Los tokens son framework-neutrales y semánticos, por tema:
|
|
|
145
181
|
}
|
|
146
182
|
```
|
|
147
183
|
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
### Componentes y patterns
|
|
151
|
-
|
|
152
|
-
Cada archivo de componente documenta propósito, variantes, tamaños, tokens, estados, comportamiento, accesibilidad, responsive, cuándo usarlo/evitarlo y relaciones. Se crean los componentes útiles para el producto y se pueden ampliar más adelante; no se obliga a generar un catálogo innecesario.
|
|
153
|
-
|
|
154
|
-
Los patterns describen composiciones como formularios, navegación, búsquedas, filtros, acciones destructivas, tablas, errores, estados vacíos y onboarding. Sus referencias a componentes y tokens permiten mostrar dependencias al actualizar el sistema.
|
|
155
|
-
|
|
156
|
-
## Crear desde una aplicación existente
|
|
157
|
-
|
|
158
|
-
El agente usa la herramienta `design_system_analyze`, que:
|
|
159
|
-
|
|
160
|
-
- Busca CSS/SCSS/LESS, vistas y componentes habituales, y reconoce frameworks/librerías desde `package.json`.
|
|
161
|
-
- Resume variables CSS, colores, radios, valores de spacing y candidatos de componentes.
|
|
162
|
-
- Marca radios cercanos o muchas decisiones visuales como posibles inconsistencias, no como errores confirmados.
|
|
163
|
-
- Limita directorios, número y tamaño de archivos; omite dependencias, builds y artefactos generados.
|
|
164
|
-
- No escribe en los archivos analizados.
|
|
165
|
-
|
|
166
|
-
El agente explica las evidencias, incertidumbres y variaciones detectadas. Pregunta antes de normalizar decisiones ambiguas; conserva por defecto la identidad reconocible y distingue formalizar/normalizar de rediseñar. Solo después de la conversación crea `design-system/`.
|
|
184
|
+
The vocabulary can grow to include typography, layout, elevation, motion, breakpoints, focus, and states. Components describe purpose, variants, tokens, behavior, accessibility, responsive behavior, and relationships. Patterns document useful compositions such as forms, navigation, filters, tables, and empty states.
|
|
167
185
|
|
|
168
|
-
|
|
186
|
+
### Meaningful, versioned updates
|
|
169
187
|
|
|
170
|
-
`/design-system/update`
|
|
188
|
+
`/design-system/update` reads the manifest and relevant documents before changing the system. A semantic token update changes that path across themes by default; prefix a path with `themes.<name>.` for a theme-specific change. The update records the rationale, finds declared token dependents, updates relevant documentation, and regenerates the preview.
|
|
171
189
|
|
|
172
|
-
|
|
190
|
+
Design-system version impact follows:
|
|
173
191
|
|
|
174
|
-
- **PATCH**
|
|
175
|
-
- **MINOR**
|
|
176
|
-
- **MAJOR**
|
|
192
|
+
- **PATCH** — compatible fixes or documentation changes.
|
|
193
|
+
- **MINOR** — compatible additions, such as a new token, component, or pattern.
|
|
194
|
+
- **MAJOR** — changes that may break existing design contracts.
|
|
177
195
|
|
|
178
|
-
|
|
196
|
+
These versions belong to the generated project design system, not the npm plugin package. Updated systems return to `draft` by default so a person can review them.
|
|
179
197
|
|
|
180
|
-
##
|
|
198
|
+
## Interactive preview
|
|
181
199
|
|
|
182
|
-
`preview/index.html`
|
|
200
|
+
`design-system/preview/index.html` is generated from the manifest, tokens, and component/pattern specifications. It includes token samples, component examples, theme switching when multiple themes exist, and interactive examples. It supports visible keyboard focus and `prefers-reduced-motion`.
|
|
183
201
|
|
|
184
|
-
|
|
202
|
+
Regenerate it in OpenCode with `/design-system/preview`, or without the plugin from the project root:
|
|
185
203
|
|
|
186
204
|
```sh
|
|
187
205
|
node design-system/tools/generate-preview.mjs
|
|
188
206
|
```
|
|
189
207
|
|
|
190
|
-
|
|
208
|
+
The standalone renderer has no external dependencies. Edit the structured Markdown and JSON—not the generated HTML—to change the system.
|
|
191
209
|
|
|
192
|
-
##
|
|
193
|
-
|
|
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.
|
|
195
|
-
|
|
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.
|
|
197
|
-
|
|
198
|
-
## Comprobación
|
|
199
|
-
|
|
200
|
-
`/design-system/check` realiza una exploración de solo lectura, compara literales de color, radios y algunas alturas de controles con los valores encontrados en tokens y presenta candidatos con ruta de archivo. Es heurística: informa la evidencia en lugar de cambiar estilos automáticamente. La arquitectura puede ampliarse con adaptadores y reglas específicas de cada framework sin cambiar el formato base.
|
|
201
|
-
|
|
202
|
-
## Desarrollo
|
|
210
|
+
## Develop and test
|
|
203
211
|
|
|
204
212
|
```sh
|
|
205
213
|
npm install
|
|
@@ -208,11 +216,29 @@ npm test
|
|
|
208
216
|
npm run build
|
|
209
217
|
```
|
|
210
218
|
|
|
211
|
-
|
|
219
|
+
Tests cover an integrated temporary-project workflow, including read-only analysis, creation and preservation of user files, managed `AGENTS.md` updates, screen briefs, multi-theme token updates, previews, checks, and path safety.
|
|
220
|
+
|
|
221
|
+
## Publish a release
|
|
222
|
+
|
|
223
|
+
The `Publish to npm` GitHub Actions workflow publishes when a `vX.Y.Z` tag is pushed, after checks pass and the tag matches the version in `package.json`. Before the first release, configure npm Trusted Publishing for the `BraveOtter/opencode-design-system` repository and the `publish.yml` workflow, and allow the direct `npm publish` action. The workflow uses OIDC, so no npm publish token needs to be stored in GitHub; npm also generates provenance automatically for this public repository.
|
|
212
224
|
|
|
213
|
-
|
|
225
|
+
To bump the package version and push its commit and tag:
|
|
214
226
|
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
227
|
+
```sh
|
|
228
|
+
npm version patch # or minor / major
|
|
229
|
+
git push --follow-tags
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
## Documentation
|
|
233
|
+
|
|
234
|
+
- [OpenCode v2 plugin guide](https://opencode.ai/v2/docs/build/plugins)
|
|
235
|
+
- [OpenCode plugin configuration](https://opencode.ai/v2/docs/plugins)
|
|
236
|
+
- [OpenCode commands](https://opencode.ai/v2/docs/commands)
|
|
237
|
+
- [OpenCode instructions and `AGENTS.md`](https://opencode.ai/v2/docs/instructions)
|
|
218
238
|
- [Plugin API reference](https://opencode.ai/v2/docs/api)
|
|
239
|
+
- [npm package](https://www.npmjs.com/package/opencode-design-system)
|
|
240
|
+
- [Report an issue](https://github.com/BraveOtter/opencode-design-system/issues)
|
|
241
|
+
|
|
242
|
+
## License
|
|
243
|
+
|
|
244
|
+
This project is licensed under the [MIT License](https://github.com/BraveOtter/opencode-design-system/blob/main/LICENSE).
|