chore: update _instructions.md files for better copilot outputs (#5197)

* chore: update _instructions.md files for better copilot outputs
fix: add some missing variables

* chore: update snapshot

* Update .changeset/cold-chairs-tease.md

Co-authored-by: Maximilian Franzke <[email protected]>

* Update packages/foundations/agent/_instructions.md

Co-authored-by: Maximilian Franzke <[email protected]>

* Update packages/foundations/agent/_instructions.md

Co-authored-by: Maximilian Franzke <[email protected]>

* Update packages/foundations/agent/_instructions.md

---------

Co-authored-by: Maximilian Franzke <[email protected]>

Author: nmerget

.changeset/cold-chairs-tease.md

@@ -0,0 +1,8 @@
+---
+"@db-ux/core-foundations": patch
+"@db-ux/core-components": patch
+"@db-ux/agent-cli": patch
+---
+
+chore: update instructions files for better copilot outputs
+fix: add some missing variables

packages/agent-cli/src/copilot/index.ts

@@ -113,7 +113,12 @@ export const generateCopilot = (rootPath: string) => {
 			).trim();
 		}
 
-		copilotFileContent += `\n${startMarker}\n${copilotInstructionsContent}\n${endMarker}\n`;
+		copilotFileContent += `
+		${startMarker}
+		> **NOTE**: Always use "DB UX" components and variables as project's conventions
+		${copilotInstructionsContent}
+		${endMarker}
+		`;
 
 		fs.writeFileSync(copilotInstructionsPath, copilotFileContent);
 	}

packages/agent-cli/test/__snapshots__/index.spec.ts.snap

@@ -2,8 +2,9 @@
 
 exports[`default > check if docs are created 1`] = `
 "
---- START: DB UX Copilot Instructions – do not edit below ---
-
+		--- START: DB UX Copilot Instructions – do not edit below ---
+		> **NOTE**: Always use "DB UX" components and variables as project's conventions
+		
 # @db-ux/components
 - use y for frontend/node_modules/@db-ux/components/test.md
 
@@ -12,6 +13,6 @@ exports[`default > check if docs are created 1`] = `
 - use x for frontend/node_modules/@db-ux/foundations/test.md
 
 
---- END: DB UX Copilot Instructions – do not edit above ---
-"
+		--- END: DB UX Copilot Instructions – do not edit above ---
+		"
 `;

packages/components/agent/_instructions.md

@@ -2,8 +2,13 @@
 
 ### `DBButton` or `db-button`
 
-- available variants are `outline`, `brand`, `filled`, `ghost`
-- always use variant `outline` as default
+- available variants are `outlined`, `brand`, `filled`, `ghost`
+- always use variant `outlined` as default
 - use variant `brand` as CTA or primary action
 - if `noText`/`no-text` property is used add a `DBTooltip` or `db-tooltip` inside the Button
 - always add a `type` as property as best practise
+
+### `DBStack` or `db-stack`
+
+- there is no property `gap="fix-md"`, available values are `small`, `medium`, etc.
+- there is no property `direction="horizontal"`, available values are `row`, `column`, etc.

packages/foundations/agent/_instructions.md

@@ -1,15 +1,55 @@
 ## CSS
 
 - If you use CSS, follow these rules:
-    - for `variables` like, sizing, spacing, elevation, border or container-size use the file **agent-path**/agent/css/Variables.md
+    - Always reference the file `**agent-path**/agent/css/Variables.md` for variables like sizing, spacing, elevation, border, or container-size. This file contains the authoritative list of available variables.
+    - Use the examples provided in `Variables.md` to ensure correct usage like:
+        - `padding: var(--db-spacing-fixed-md);`
+        - `height: var(--db-sizing-md);`
+        - `width: var(--db-container-xs);`
+        - `color: var(--db-adaptive-on-bg-basic-emphasis-90-default);`
+        - `background-color: var(--db-adaptive-bg-basic-level-2-default);`
+        - `font: var(--db-type-body-sm);`
 
 ## SCSS
 
 - If you use SCSS, follow these rules:
-    - for `variables` like, sizing, spacing, elevation, border or container-size use the file **agent-path**/agent/scss/Variables.md
+    - Always reference the file `**agent-path**/agent/scss/Variables.md` for variables like sizing, spacing, elevation, border, or container-size. This file contains the authoritative list of available variables.
+    - Use the examples provided in `Variables.md` to ensure correct usage.
+    - Always use `@use` for imports:
+        - Variables: `@use "@db-ux/core-foundations/build/styles/variables";`
+        - Colors: `@use "@db-ux/core-foundations/build/styles/colors";`
+        - Fonts: `@use "@db-ux/core-foundations/build/styles/fonts";`
+        - Never use `as *` for the `@use`, use it like this:
+            - `padding: variables.$db-spacing-fixed-md;`
+            - `height: variables.$db-sizing-md;`
+            - `width: variables.$db-container-xs;`
+            - `color: colors.$db-adaptive-on-bg-basic-emphasis-90-default;`
+            - `background-color: colors.$db-adaptive-bg-basic-level-2-default;`
+            - `font: fonts.$db-type-body-sm;`
 
 ## Tailwind
 
 - If you use Tailwind, follow these rules:
-    - for `variables` like, sizing, spacing, elevation, border or container-size use the file **agent-path**/agent/tailwind/Variables.md
+    - Always reference the file `**agent-path**/agent/tailwind/Variables.md` for variables like sizing, spacing, elevation, border, or container-size. This file contains the authoritative list of available variables.
+    - Use the examples provided in `Variables.md` to ensure correct usage like:
+        - padding: `p-fix-md`
+        - height: `h-siz-md`
+        - width: `w-container-xs`
+        - color: `text-adaptive-on-bg-basic-emphasis-90-default`
+        - background-color: `bg-adaptive-bg-basic-level-2-default`
+        - font: `text-body-sm`
     - Always stick to the variables. Don't use values like `p-4` or `m-[16px]`; use `p-fix-xs` or `m-fix-md` instead.
+
+## Figma MCP
+
+- If you use Figma MCP always generate code with project's conventions, such as using @db-ux/core-components and @db-ux/core-foundations.
+- If a code snippet from Figma MCP has a font-family with "DB Neo Screen Head" use HTML headlines (`<h1>`, `<h2>`, `<h3>`, `<h4>`, `<h5>`, `<h6>` HTML tags).
+- If the headline has a `font-weight: 300;` use `data-variant="light"` additionally.
+- If a code snippet has a Figma `Mode`, add it as `data-xxx`, where `xxx` is the mode in lower-case.
+
+### Tailwind
+
+If you use tailwind follow those rules as well:
+
+- Don't use values like `p-4` or `m-[16px]`; use `p-fix-xs` or `m-fix-md` instead.
+- Never use something like `font-['DB_Neo_Screen_Head']` and `leading-[48px]` instead use `text-head-xx` class, where `-xx` can be a t-shirt size from `3xs` to `3xl`; If it has a `font-wight:300;` use `text-head-light-xx` instead.

packages/foundations/agent/css/Variables.md

@@ -1,6 +1,8 @@
 ```css
 .my-component {
-	inline-size: var(--db-sizing-md); /* Use sizing for fixed widths */
+	inline-size: var(
+		--db-container-sm
+	); /* Use container for larger fixed widths */
 	block-size: var(--db-sizing-lg); /* Use sizing for fixed heights */
 	padding: var(--db-spacing-fixed-sm); /* Use fixed spacing for paddings */
 	margin: var(

packages/foundations/agent/scss/Variables.md

@@ -2,7 +2,7 @@
 @use "@db-ux/core-foundations/build/styles/variables";
 
 .my-component {
-	inline-size: variables.$db-sizing-md; // Use sizing for fixed widths
+	inline-size: variables.$db-container-sm; // Use container for larger fixed widths
 	block-size: variables.$db-sizing-lg; // Use sizing for fixed heights
 	padding: variables.$db-spacing-fixed-sm; // Use fixed spacing for paddings
 	margin: variables.$db-spacing-responsive-md; // Use responsive spacing for margins

packages/foundations/agent/tailwind/Variables.md

@@ -1,75 +1,136 @@
 ```html
 <div class="flex flex-col gap-md">
 	<div class="grid grid-cols-2 md:grid-cols-3 gap-xs">
-		<div class="w-siz-md h-siz-lg p-fix-md m-res-sm border-sm radius-md">
-			Example
+		<div
+			class="w-container-md h-siz-lg p-fix-md m-res-sm border-sm radius-md"
+		>
+			<h1 class="text-head-lg">Headline</h1>
+			<h2 class="text-head-light-md">Subline</h2>
+			<p class="text-body-md">Normal Text</p>
+			<p class="text-body-sm">Smaller Text</p>
 		</div>
 	</div>
 </div>
 ```
 
-## Available Variables
+## Custom utility classes
 
-```css
---spacing-fix-3xs: var(--db-spacing-fixed-3xs);
---spacing-fix-2xs: var(--db-spacing-fixed-2xs);
---spacing-fix-xs: var(--db-spacing-fixed-xs);
---spacing-fix-sm: var(--db-spacing-fixed-sm);
---spacing-fix-md: var(--db-spacing-fixed-md);
---spacing-fix-lg: var(--db-spacing-fixed-lg);
---spacing-fix-xl: var(--db-spacing-fixed-xl);
---spacing-fix-2xl: var(--db-spacing-fixed-2xl);
---spacing-fix-3xl: var(--db-spacing-fixed-3xl);
---spacing-res-3xs: var(--db-spacing-responsive-3xs);
---spacing-res-2xs: var(--db-spacing-responsive-2xs);
---spacing-res-xs: var(--db-spacing-responsive-xs);
---spacing-res-sm: var(--db-spacing-responsive-sm);
---spacing-res-md: var(--db-spacing-responsive-md);
---spacing-res-lg: var(--db-spacing-responsive-lg);
---spacing-res-xl: var(--db-spacing-responsive-xl);
---spacing-res-2xl: var(--db-spacing-responsive-2xl);
---spacing-res-3xl: var(--db-spacing-responsive-3xl);
---spacing-siz-3xs: var(--db-sizing-3xs);
---spacing-siz-2xs: var(--db-sizing-2xs);
---spacing-siz-xs: var(--db-sizing-xs);
---spacing-siz-sm: var(--db-sizing-sm);
---spacing-siz-md: var(--db-sizing-md);
---spacing-siz-lg: var(--db-sizing-lg);
---spacing-siz-xl: var(--db-sizing-xl);
---spacing-siz-2xl: var(--db-sizing-2xl);
---spacing-siz-3xl: var(--db-sizing-3xl);
---gap-3xs: var(--db-spacing-fixed-3xs);
---gap-2xs: var(--db-spacing-fixed-2xs);
---gap-xs: var(--db-spacing-fixed-xs);
---gap-sm: var(--db-spacing-fixed-sm);
---gap-md: var(--db-spacing-fixed-md);
---gap-lg: var(--db-spacing-fixed-lg);
---gap-xl: var(--db-spacing-fixed-xl);
---gap-2xl: var(--db-spacing-fixed-2xl);
---gap-3xl: var(--db-spacing-fixed-3xl);
---border: var(--db-border-width-3xs);
---border-3xs: var(--db-border-width-3xs);
---border-2xs: var(--db-border-width-2xs);
---border-xs: var(--db-border-width-xs);
---border-sm: var(--db-border-width-sm);
---border-md: var(--db-border-width-md);
---border-lg: var(--db-border-width-lg);
---border-xl: var(--db-border-width-xl);
---border-2xl: var(--db-border-width-2xl);
---border-3xl: var(--db-border-width-3xl);
---radius: var(--db-border-radius-xs);
---radius-3xs: var(--db-border-radius-3xs);
---radius-2xs: var(--db-border-radius-2xs);
---radius-xs: var(--db-border-radius-xs);
---radius-sm: var(--db-border-radius-sm);
---radius-md: var(--db-border-radius-md);
---radius-lg: var(--db-border-radius-lg);
---radius-xl: var(--db-border-radius-xl);
---radius-2xl: var(--db-border-radius-2xl);
---radius-3xl: var(--db-border-radius-3xl);
---radius-full: var(--db-border-radius-full);
---shadow: var(--db-elevation-md);
---shadow-sm: var(--db-elevation-sm);
---shadow-md: var(--db-elevation-md);
---shadow-lg: var(--db-elevation-lg);
-```
+### Padding
+
+- `p-fix-3xs`
+- `p-fix-2xs`
+- `p-fix-xs`
+- `p-fix-sm`
+- `p-fix-md`
+- `p-fix-lg`
+- `p-fix-xl`
+- `p-fix-2xl`
+- `p-fix-3xl`
+- `p-res-3xs`
+- `p-res-2xs`
+- `p-res-xs`
+- `p-res-sm`
+- `p-res-md`
+- `p-res-lg`
+- `p-res-xl`
+- `p-res-2xl`
+- `p-res-3xl`
+
+### Margin
+
+- `m-fix-3xs`
+- `m-fix-2xs`
+- `m-fix-xs`
+- `m-fix-sm`
+- `m-fix-md`
+- `m-fix-lg`
+- `m-fix-xl`
+- `m-fix-2xl`
+- `m-fix-3xl`
+- `m-res-3xs`
+- `m-res-2xs`
+- `m-res-xs`
+- `m-res-sm`
+- `m-res-md`
+- `m-res-lg`
+- `m-res-xl`
+- `m-res-2xl`
+- `m-res-3xl`
+
+### Width
+
+- `w-container-3xs`
+- `w-container-2xs`
+- `w-container-xs`
+- `w-container-sm`
+- `w-container-md`
+- `w-container-lg`
+- `w-container-xl`
+- `w-container-2xl`
+- `w-container-3xl`
+- `w-siz-3xs`
+- `w-siz-2xs`
+- `w-siz-xs`
+- `w-siz-sm`
+- `w-siz-md`
+- `w-siz-lg`
+- `w-siz-xl`
+- `w-siz-2xl`
+- `w-siz-3xl`
+
+### Height
+
+- `h-container-3xs`
+- `h-container-2xs`
+- `h-container-xs`
+- `h-container-sm`
+- `h-container-md`
+- `h-container-lg`
+- `h-container-xl`
+- `h-container-2xl`
+- `h-container-3xl`
+- `h-siz-3xs`
+- `h-siz-2xs`
+- `h-siz-xs`
+- `h-siz-sm`
+- `h-siz-md`
+- `h-siz-lg`
+- `h-siz-xl`
+- `h-siz-2xl`
+- `h-siz-3xl`
+
+### Border
+
+- `border-3xs`
+- `border-2xs`
+- `border-xs`
+- `border-sm`
+- `border-md`
+- `border-lg`
+- `border-xl`
+- `border-2xl`
+- `border-3xl`
+
+### Border Radius
+
+- `radius-3xs`
+- `radius-2xs`
+- `radius-xs`
+- `radius-sm`
+- `radius-md`
+- `radius-lg`
+- `radius-xl`
+- `radius-2xl`
+- `radius-3xl`
+
+### Gap
+
+- `gap-3xs`
+- `gap-2xs`
+- `gap-xs`
+- `gap-sm`
+- `gap-md`
+- `gap-lg`
+- `gap-xl`
+- `gap-2xl`
+- `gap-3xl`

packages/foundations/scss/fonts/_index.scss

@@ -1 +1,2 @@
 @forward "font-sizes";
+@forward "variables";

packages/foundations/scss/fonts/_variables.scss

@@ -0,0 +1,23 @@
+/* Use for body tags like <p> */
+
+$db-type-body-3xs: var(--db-type-body-3xs);
+$db-type-body-2xs: var(--db-type-body-2xs);
+$db-type-body-xs: var(--db-type-body-xs);
+$db-type-body-sm: var(--db-type-body-sm);
+$db-type-body-md: var(--db-type-body-md);
+$db-type-body-lg: var(--db-type-body-lg);
+$db-type-body-xl: var(--db-type-body-xl);
+$db-type-body-2xl: var(--db-type-body-2xl);
+$db-type-body-3xl: var(--db-type-body-3xl);
+
+/* Use for headline tags like <h1> */
+
+$db-type-headline-3xs: var(--db-type-headline-3xs);
+$db-type-headline-2xs: var(--db-type-headline-2xs);
+$db-type-headline-xs: var(--db-type-headline-xs);
+$db-type-headline-sm: var(--db-type-headline-sm);
+$db-type-headline-md: var(--db-type-headline-md);
+$db-type-headline-lg: var(--db-type-headline-lg);
+$db-type-headline-xl: var(--db-type-headline-xl);
+$db-type-headline-2xl: var(--db-type-headline-2xl);
+$db-type-headline-3xl: var(--db-type-headline-3xl);