@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/ui-ugui/references/layout-and-anchors.md

@@ -0,0 +1,61 @@
+# Layout Components
+
+**Layout Groups control child sizing:**
+- When a parent has a Layout Group, it manages child RectTransforms
+- Children's anchors and sizeDelta may be overridden by the parent
+- Understand whether the parent or child controls size before setting values
+
+**Vertical/Horizontal Layout Groups:**
+- Control Child Size: determines if parent sets child dimensions
+- Child Force Expand: determines if children stretch to fill space
+- If Control Child Size is off, children must have explicit sizes
+
+**Avoiding layout conflicts:**
+- Do not manually set child anchors/size when parent controls them
+- Do not add Layout Group to an element that should have fixed size
+- Nested Layout Groups require careful configuration of each level
+- When layout is wrong, check parent settings before modifying child
+- ContentSizeFitter on the **same** object as a Layout Group that has Control Child Size enabled = conflict
+- ContentSizeFitter on a child whose parent has Control Child Size enabled = ContentSizeFitter is overridden (wasted)
+- When using ContentSizeFitter with a Layout Group parent, disable Control Child Size on the parent for the relevant axis
+- Common pattern: ScrollView Content should have ContentSizeFitter + VerticalLayoutGroup where VLG controls children but ContentSizeFitter sizes the Content itself
+
+**Grid Layout Group:**
+- For inventory grids, card layouts
+- Cell Size must be set explicitly — children are sized to match
+- Constraint controls row/column limits
+
+**Content Size Fitter:**
+- Horizontal/Vertical Fit: Preferred Size
+- Use on containers that should size to their content
+- Requires a layout element or text component to provide preferred size
+
+# RectTransform Anchoring
+
+**Elements must have non-zero size to be visible:**
+- Set explicit width/height via sizeDelta, or
+- Use stretch anchors with proper offsets, or
+- Let a parent Layout Group control size (with Control Child Size enabled)
+
+**Anchor configuration order:**
+1. Set anchor preset first (corner, edge, or stretch)
+2. Then set position/offset values
+3. Verify the resulting size is non-zero
+
+**Common patterns:**
+- **Stretch anchors** — for responsive elements that fill available space
+- **Corner anchors** — for fixed-position, fixed-size elements
+- **Edge anchors** — for elements that stretch in one direction only
+
+**Positioning from natural language descriptions:**
+When the user describes a position (e.g., "top right", "bottom bar", "left side"):
+1. Determine if it's a **corner** (fixed point), an **edge** (stretch along one axis), or **fill** (stretch both axes)
+2. Set anchor min and anchor max — for corners these are the same point; for edges/fill they span a range
+3. **Set pivot to match the anchor point** — pivot must align with where the element is anchored, not left at the default (0.5, 0.5). A "top right" element needs pivot at the top-right corner; a "top bar" needs pivot at the top edge center
+4. Set position/offset values **after** anchors and pivot are configured
+
+**Visibility checklist:**
+- Width and height are both greater than zero
+- Element is within parent bounds
+- Element is not obscured by siblings (check hierarchy order)
+- Image component has a sprite or color with alpha > 0

package/skills/ui-ugui/references/scrollview-setup.md

@@ -0,0 +1,29 @@
+# ScrollView Setup
+
+ScrollRect requires a specific hierarchy to function correctly. Missing or misordered components cause jitter, duplication, or non-scrollable content.
+
+**Required hierarchy:**
+```
+ScrollView (ScrollRect)
+├── Viewport (RectTransform + Mask + Image)
+│   └── Content (RectTransform + VerticalLayoutGroup + ContentSizeFitter)
+│       └── [Children — static or added at runtime]
+└── Scrollbar (optional)
+```
+
+**Setup rules:**
+- **ScrollRect** component goes on the root ScrollView object
+- **Viewport** must have a `Mask` component and an `Image` component (Mask requires Image)
+- **Content** must have `ContentSizeFitter` with Vertical Fit set to "Preferred Size" so the scroll area grows with children
+- ScrollRect references: assign Content to `Content`, Viewport to `Viewport`, and optionally assign a Scrollbar
+- Content can contain static children (settings lists, about pages) or be populated dynamically at runtime
+
+**Dynamic population (runtime items):**
+- **Clear existing children** before populating to prevent duplication on panel re-open
+- Instantiate item prefabs as children of the Content object
+- The ContentSizeFitter + VerticalLayoutGroup on Content will automatically size the scrollable area
+
+**Common failures:**
+- Items duplicated on every open → Content not cleared before populating
+- Content not scrollable → missing ContentSizeFitter on Content, or Viewport missing Mask
+- Jitter/flickering → ContentSizeFitter conflict with parent Layout Group (see "Avoiding layout conflicts" in the main skill)

package/skills/ui-uitk/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: ui-uitk
+description: Understands, edits, and generates Unity UI Toolkit UXML and USS with flex layouts. Use for requests involving UI Toolkit, UIElements, UIDocument, PanelSettings, custom elements, or UI runtime binding.
+---
+
+Understand existing Unity UI Toolkit code, make targeted edits, generate new UXML/USS files, Manipulators, and handle UI runtime binding.
+
+## References
+
+Read these as needed:
+- [references/uss-guide.md](references/uss-guide.md) — USS patterns and examples
+- [references/svg-icons.md](references/svg-icons.md) — SVG icon generation (only when generating icons)
+- [references/common-issues.md](references/common-issues.md) — Common mistakes to avoid
+- [references/ui-runtime-binding.md](references/ui-runtime-binding.md) — Patterns and guide to bind data to UI at runtime (only when requested or when bindings are involved)
+- [references/painter2d.md](references/painter2d.md) — Painter2D API for custom visuals: gradients, shapes, arcs, procedural drawing (read this whenever gradients, custom shapes, progress rings, procedural drawing, or any visual beyond what USS can express is needed)
+- [references/pointermanipulator-guide.md](references/pointermanipulator-guide.md) — Patterns and guide to create and use Manipulators (only when requested or when manipulators are involved). This helps with setting up drag and drop features or simple event handling for a Visual Element.
+- [references/custom-elements.md](references/custom-elements.md) — Custom UI Element patterns and guide to create reusable components with UXML, USS, and C#. This helps with creating complex UI components for reuse across the project.
+
+Paths are relative to this skill's folder — read `references/uss-guide.md` directly.
+
+## Understanding
+
+When explaining UI structure, use this format:
+```
+[ElementType] name="elementName" class="class1 class2"
+├── [ChildType] name="childName"
+│   └── [GrandchildType]
+└── [ChildType] class="another-class"
+```
+
+## Editing
+
+**Common edit requests:**
+
+| Request | Action |
+|---------|--------|
+| "Change button color" | Edit USS selector for that button |
+| "Add a label here" | Add element to UXML at specified location |
+| "Make this bigger" | Edit width/height in USS |
+| "Hide this element" | Add `display: none` to USS or remove from UXML |
+| "Rename this element" | Update `name` attribute in UXML |
+
+**Don't over-edit:**
+- Change only what's requested
+- Preserve formatting and structure
+- Don't "improve" unrelated code
+- Don't add comments unless asked
+- For targeted changes, prefer modifying specific elements or selectors over rewriting entire files — but use judgment; if a change touches most of the file, a rewrite may be cleaner
+- Be careful not to accidentally drop existing elements, styles, or references when making edits
+- **When editing USS**, focus on the properties and selectors relevant to the request — avoid unnecessary reorganization, but restructure if the change genuinely requires it
+
+## Validation
+
+There is no way to validate UXML or USS from outside the Editor — Unity parses these
+files on import and reports problems in the Console. Write the files, then have the
+user check the result.
+
+**Workflow:**
+
+1. Write the complete file to its target path in the project. Do not write partial or
+   draft content — a half-written UXML file is a parse error the moment the Editor
+   picks it up.
+2. Ask the user to focus the Unity Editor. That triggers a reimport of the changed
+   assets.
+3. Ask them to report anything in the Console. UXML parse errors name the file and
+   line; USS problems appear as warnings about unknown properties or selectors.
+4. Fix what they report and repeat from step 1.
+
+**Because feedback costs a user round-trip, get it right the first time:**
+
+- Finish all files before asking the user to check, so one reimport covers everything
+  rather than one per file.
+- Re-read `references/uss-guide.md` and `references/common-issues.md` before writing,
+  rather than after an error comes back.
+- Watch for the mistakes that survive a parse but render wrong — those will not appear
+  in the Console at all, so the user has to eyeball the UI. `references/common-issues.md`
+  lists them.
+
+## Generation
+
+When creating new UI:
+
+**Generate only what is requested:**
+
+| Request | Output |
+|---------|--------|
+| USS only | `.uss` file only |
+| UXML only | `.uxml` file only |
+| UI screen / menu / panel | `.uss` + `.uxml` only |
+| "with code" / "with logic" / "functional" | `.uss` + `.uxml` + `.cs` |
+
+**These do NOT imply C#:**
+- "proper buttons" → well-styled Button elements
+- "currency display" → a Label element
+- "working UI" → valid UXML/USS that renders
+- "inventory screen" → visual layout only
+- "inventory system" / "equipment system" / "crafting system" → Ask: "Should items be draggable?" If yes, see `references/pointermanipulator-guide.md` for patterns
+
+**Generation workflow:**
+1. **Analyze** — Determine exactly what files are needed. No extras.
+2. **Search** — Find existing USS, UXML, assets. Don't assume paths.
+3. **Follow project patterns** — Match folder structure and naming conventions.
+4. **Reuse** — Check for shared stylesheets. Reuse if appropriate.
+5. **Write USS first** — Verify against restrictions below.
+6. **Write UXML** — Reference the USS, verify structure.
+7. **Write the files out complete** — never partial content; see Validation above for
+   how errors come back and why one round of files beats several.
+8. **Scene setup** — Assign PanelSettings if adding UI to scene.
+9. **Data binding** — If requested, add C# script with runtime data binding patterns (see `references/ui-runtime-binding.md`). Generate the scriptable object asset if needed. Assign the asset to the UI element root in UXML or via datasource in C#.
+
+**Color, visibility, and specification rules:**
+- **Ensure text is readable by default:** When choosing colors, ensure text contrasts with its background — but respect intentional low-contrast uses (disabled states, placeholder text, decorative elements). When using design tokens, check that text and background variables provide adequate contrast.
+- **Honor exact values:** User-specified hex colors, pixel dimensions, spacing — use exactly as given. Do not approximate or substitute.
+
+**Styling / Theme**
+When styling UI or adjusting theme make sure to not only apply to the elements directly in the current UXML but also to the core elements of UI Toolkit which are composed of several child elements usually.
+
+## Conventions
+
+**Follow project patterns first.** Search existing files before applying defaults.
+
+| Type | Convention | Good | Bad |
+|------|------------|------|-----|
+| `name` attribute | camelCase | `submitButton` | `submit-button` |
+| `class` attribute / USS | kebab-case | `.submit-button` | `.submitButton` |
+| File paths | Feature folders | `Assets/UI/Inventory/` | `Assets/Scripts/UI/` |
+
+**Output format:**
+```uxml Filename.uxml
+<ui:UXML>...</ui:UXML>
+```
+```uss Filename.uss
+.class { ... }
+```
+
+## USS Restrictions
+
+Unity's USS is a subset of CSS. These properties do NOT exist — NEVER use them:
+
+| NEVER Use | Use Instead |
+|-----------|-------------|
+| `border` shorthand | `border-width`, `border-color` separately |
+| `gap` | `margin` on children |
+| `z-index` | DOM order or parent nesting |
+| `pointer-events` | `picking-mode` UXML attribute |
+| `filter` | Not supported |
+| `outline` | `border-*` properties |
+| `box-shadow` | Nested elements or background image |
+| `:first-child`, `:last-child`, `:nth-child` | Explicit classes |
+| `[attribute]` selectors | Explicit classes |
+| `transition-property: <value>` | Omit entirely, or `none`/`initial`/`inherit` only |
+| `linear-gradient()`, `radial-gradient()` | Custom `VisualElement` with Painter2D (see `references/painter2d.md`) |
+
+**Inline styles:** NEVER use `style="..."` in UXML. All styling in USS only.
+
+**External URLs:** NEVER use `url()` with external paths. Only `url("project://database/Assets/...")`.
+
+**Prefer flexible layouts over hardcoded sizes:**
+- Use `flex-grow`, `flex-shrink`, or `%` instead of fixed `width`/`height` values
+- Let elements flow naturally and be constrained by their parent container
+- Set explicit pixel sizes only on root containers or when a fixed size is truly required
+- Child elements should adapt to available space rather than define their own dimensions
+
+## USS Brevity
+
+- No default values (`flex-direction: column` is default)
+- No default fonts
+- No redundant constraints (`width: 100px` doesn't need `min-width`/`max-width`)
+- No overlapping properties (`flex: 1` already sets grow/shrink)
+- Simplest selector that works
+- Never duplicate selectors
+
+## UXML
+
+Every file must:
+1. Declare namespace: `<ui:UXML xmlns:ui="UnityEngine.UIElements">`
+2. Link stylesheet(s): `<ui:Style src="Screen.uss" />`
+3. Have exactly one top-level container
+4. **No `style="..."` attributes** — use USS only
+
+```uxml
+<ui:UXML xmlns:ui="UnityEngine.UIElements">
+  <ui:Style src="Panel.uss" />
+  <ui:VisualElement name="root" class="panel">
+    <!-- content -->
+  </ui:VisualElement>
+</ui:UXML>
+```
+
+## Events and Interactivity
+- Use Pointer Manipulators for event handling and interactivity on a VisualElement (see `references/pointermanipulator-guide.md`)
+- If drag and drop is requested then write a pointer Manipulator and attach it to the relevant Visual Element in UXML or via C#.
+- For simple click events, you can use the `clickable` manipulator in UXML
+- For more advanced interactions, create use more traditional event callbacks in C# and attach them to elements as needed
+
+**For inventory and crafting systems:**
+- When users request an "inventory system", "equipment system", or "crafting system", ask explicitly: "Should players be able to drag and drop items?"
+- If yes, read `references/pointermanipulator-guide.md` for inventory/crafting-specific patterns
+- If no or unclear, create static layout only
+
+## Assets
+
+**Do NOT reference `UnityDefaultRuntimeTheme.tss`** or Unity's built-in theme icons.
+
+**Icon priority:**
+1. Reuse existing project icons
+2. Generate SVG (see `references/svg-icons.md`)
+3. Image generators (last resort)
+
+**Reference format:**
+```uss
+background-image: url("project://database/Assets/UI/Textures/icon.png");
+```
+
+## Scene Setup
+
+**PanelSettings is required** — UI won't render without it.
+
+1. Search for existing PanelSettings asset
+2. If none, create generic: `Assets/UI/PanelSettings.asset`
+3. Assign to UIDocument's `Panel Settings` field
+
+Skip for Editor UI (EditorWindow, PropertyDrawer).
+
+## C# (Only When Requested)
+
+- Style via USS classes (`AddToClassList()`) — never use `element.style.*` as inline styles have higher specificity than USS selectors, making them impossible to override via stylesheets, and add per-element memory overhead
+- UITK uses TextCore text assets — use `FontAsset`, `TextStyleSheet`, and `TextSettings`, not their TextMeshPro equivalents (`TMP_FontAsset`, etc.)
+- Place scripts in same folder as UXML/USS

package/skills/ui-uitk/references/common-issues.md

@@ -0,0 +1,74 @@
+# Common USS/UXML Issues
+
+## Transitions on :hover
+
+Transitions must be defined on the base class, not the hover state:
+
+```uss
+/* WRONG - won't animate on hover-out */
+.button:hover {
+  background-color: blue;
+  transition-duration: 0.2s;
+}
+
+/* CORRECT */
+.button {
+  background-color: white;
+  transition-duration: 0.2s;
+}
+.button:hover {
+  background-color: blue;
+}
+```
+
+## Hardcoded Percentage Widths
+
+Avoid hardcoded percentages for flexible layouts:
+
+```uss
+/* AVOID */
+.column {
+  width: 33%;
+}
+
+/* PREFER */
+.column {
+  flex-grow: 1;
+}
+```
+
+## Unclosed Brackets
+
+Always ensure brackets are properly closed:
+
+```uss
+/* WRONG - missing closing bracket */
+.panel {
+  padding: 16px;
+
+.button {
+  color: white;
+}
+
+/* CORRECT */
+.panel {
+  padding: 16px;
+}
+
+.button {
+  color: white;
+}
+```
+
+## Referencing Unity Theme
+
+**Do NOT reference `UnityDefaultRuntimeTheme.tss`** or built-in theme icons.
+
+Create custom styles or reuse project assets instead.
+
+## Performance Issues
+
+- **Inline styles** cause per-element memory overhead
+- **`:hover` on parents** with many children invalidates entire hierarchies
+- **Many classes per element** decreases selector performance linearly
+- **Large hierarchies** are the main performance factor

package/skills/ui-uitk/references/custom-elements.md

@@ -0,0 +1,241 @@
+# Custom VisualElements in UI Toolkit
+
+Guide for creating custom VisualElements using Unity 6+ `[UxmlElement]` and `[UxmlAttribute]` attributes.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Requirements](#requirements)
+- [Supported Property Types](#supported-property-types)
+- [Advanced Patterns](#advanced-patterns)
+- [Best Practices](#best-practices)
+- [UXML Namespace Declaration](#uxml-namespace-declaration)
+- [UI Builder Integration](#ui-builder-integration)
+- [Summary](#summary)
+
+## Overview
+
+Unity 6+ uses attribute-based custom elements. The old factory pattern (`IUxmlFactory`, `UxmlTraits`) is **deprecated**.
+
+### ⚠ CRITICAL: Namespace Declaration
+
+**Never include assembly names in UXML namespace declarations:**
+
+```xml
+❌ WRONG: xmlns:custom="Game.UI.Custom, Assembly-CSharp"
+✅ CORRECT: xmlns:custom="Game.UI.Custom"
+```
+
+**Format**: `xmlns:prefix="Namespace.Path"` (namespace only, no assembly)
+
+### Basic Pattern
+
+```csharp
+[UxmlElement]
+public partial class MyElement : VisualElement
+{
+    [UxmlAttribute]
+    public string myValue { get; set; }
+}
+```
+
+```xml
+<ui:UXML xmlns:ui="UnityEngine.UIElements"
+         xmlns:custom="Game.UI.Custom">
+    <custom:MyElement my-value="Hello" />
+</ui:UXML>
+```
+
+## Requirements
+
+1. **[UxmlElement]** attribute on the class
+2. **partial** keyword required
+3. Inherit from **VisualElement** or subclass
+4. **[UxmlAttribute]** on exposed properties
+
+### Property Naming
+
+C# camelCase → UXML kebab-case:
+- `myStringValue` → `my-string-value`
+- `maxHealth` → `max-health`
+
+### Example
+
+```csharp
+[UxmlElement]
+public partial class CustomLabel : Label
+{
+    [UxmlAttribute]
+    public Color textColor { get; set; } = Color.white;
+
+    [UxmlAttribute]
+    public int fontSize { get; set; } = 14;
+
+    public CustomLabel()
+    {
+        RegisterCallback<GeometryChangedEvent>(evt => {
+            style.color = textColor;
+            style.fontSize = fontSize;
+        });
+    }
+}
+```
+
+```xml
+<custom:CustomLabel text="Hello" text-color="rgb(255,215,0)" font-size="24" />
+```
+
+## Supported Property Types
+
+**Basic**: `string`, `int`, `float`, `bool`, `Color`
+**Unity**: `Texture2D`, `Sprite`, `Font`
+**Enums**: Any enum type
+**Collections**: `List<T>`, `T[]`
+
+### Image Handling
+
+**Static images** (don't change) → Use USS:
+```css
+.icon { background-image: url('project://Assets/UI/Icons/fireball.png'); }
+```
+
+**Dynamic images** (change per instance) → Use `[UxmlAttribute]`:
+```csharp
+[UxmlAttribute]
+public Sprite portrait { get; set; }  // Different per character
+```
+
+## Advanced Patterns
+
+### Validation Attributes
+
+```csharp
+[UxmlAttribute]
+[Range(0, 100)]
+[Tooltip("Current health value")]
+public float health { get; set; } = 100f;
+```
+
+Improves UI Builder inspector experience.
+
+### Custom Attribute Names
+
+```csharp
+[UxmlAttribute("hp")]
+public float health { get; set; }  // Use "hp" in UXML
+```
+
+### Custom Type Converters
+
+Use `UxmlAttributeConverter<T>` when a property's type is not natively supported by UXML (e.g. structs, complex data objects). An example below implements `FromString` to parse the UXML attribute string into the specified type, then register it with `[UxmlAttributeConverter]` on the property.
+
+```csharp
+public class HealthDataConverter : UxmlAttributeConverter<HealthData>
+{
+    public override HealthData FromString(string value)
+    {
+        var parts = value.Split(',');
+        return new HealthData { current = float.Parse(parts[0]), max = float.Parse(parts[1]) };
+    }
+}
+
+[UxmlAttribute]
+[UxmlAttributeConverter(typeof(HealthDataConverter))]
+public HealthData healthData { get; set; }
+```
+
+### Custom Property Drawers
+
+Create custom UI Builder inspector controls for your attributes:
+
+```csharp
+// 1. Custom attribute
+public class SliderDrawerAttribute : PropertyAttribute { }
+
+// 2. Property drawer
+[CustomPropertyDrawer(typeof(SliderDrawerAttribute))]
+public class SliderDrawerPropertyDrawer : PropertyDrawer
+{
+    public override VisualElement CreatePropertyGUI(SerializedProperty property)
+    {
+        var field = new SliderInt(0, 100) { label = property.displayName };
+        field.BindProperty(property);
+        return field;
+    }
+}
+
+// 3. Usage
+[UxmlElement]
+public partial class StyledButton : Button
+{
+    [UxmlAttribute]
+    [SliderDrawer]
+    public int intensity { get; set; } = 50;
+}
+```
+
+**Override existing properties** with custom drawers:
+
+```csharp
+[UxmlElement]
+public partial class CustomIntField : IntegerField
+{
+    // Override base 'value' property to use slider drawer in UI Builder
+    [UxmlAttribute("value"), SliderDrawer]
+    internal int myValue
+    {
+        get => this.value;
+        set => this.value = value;
+    }
+}
+```
+
+This customizes how properties appear in the UI Builder inspector.
+
+
+## Best Practices
+
+1. **Always use `partial`** - Required for [UxmlElement]
+2. **Provide defaults** - `public float radius { get; set; } = 30f;`
+3. **Update on changes** - Use property setters to call `UpdateVisuals()` or `MarkDirtyRepaint()`
+4. **Use backing fields** - When validation or change detection needed
+5. **USS for styling** - Add class names and style via USS, not inline styles
+6. **Static images → USS, Dynamic → C#** - Use USS `background-image` for fixed images
+7. **Document elements** - Add XML comments for better developer experience
+
+## UXML Namespace Declaration
+
+### Rules
+
+1. **Namespace only** - No assembly name, no commas
+2. **Exact match** - Must match C# namespace exactly (case-sensitive)
+3. **Format**: `xmlns:prefix="Namespace.Path"`
+
+### Examples
+
+```xml
+<!-- ✅ Single namespace -->
+<ui:UXML xmlns:ui="UnityEngine.UIElements"
+         xmlns:custom="Game.UI.Custom">
+    <custom:RadialProgress />
+</ui:UXML>
+
+<!-- ✅ Multiple namespaces -->
+<ui:UXML xmlns:ui="UnityEngine.UIElements"
+         xmlns:hud="Game.UI.HUD"
+         xmlns:menu="Game.UI.Menu">
+    <hud:HealthBar />
+    <menu:SettingsPanel />
+</ui:UXML>
+```
+
+### Common Mistakes
+
+```xml
+❌ xmlns:custom="Game.UI.Custom, Assembly-CSharp"  (assembly name)
+❌ xmlns:custom="game.ui.custom"                    (wrong case)
+❌ xmlns:custom="Custom"                            (incomplete)
+❌ xmlns:custom="Game.UI.Custom.RadialProgress"     (class name)
+
+✅ xmlns:custom="Game.UI.Custom"                    (correct)
+```