@newlogic-digital/core 4.0.0-rc.8 → 4.0.0

package/bin/newlogic-core.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+import { styleText } from 'node:util'
+import { getPackageInfo } from 'vituum/utils/common.js'
+
+const { name } = getPackageInfo(new URL('../package.json', import.meta.url).href)
+const [command] = process.argv.slice(2)
+
+if (command === 'postinstall') {
+  await import('../src/createEslintStylisticConfig.js')
+  await import('../src/linkAgentSkills.js')
+}
+else {
+  console.error(`${styleText(['cyan', 'bold'], name)} ${styleText('red', `Unknown command "${command ?? ''}".`)}`)
+  process.exitCode = 1
+}

package/index.js

@@ -25,6 +25,7 @@ const defaultOptions = {
     assets: [
       './src/styles/*.{css,pcss,scss,sass,less,styl,stylus}',
       './src/scripts/*.{js,ts,mjs}',
+      './src/assets/**/*',
     ],
     pages: [
       './src/pages/**/*.{json,latte,twig,liquid,njk,hbs,pug,html}',

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@newlogic-digital/core",
   "type": "module",
-  "version": "4.0.0-rc.8",
+  "version": "4.0.0",
   "main": "index.js",
+  "bin": {
+    "newlogic-core": "./bin/newlogic-core.js"
+  },
   "author": "New Logic Studio s.r.o.",
   "description": "Set of tools that can be used to create modern web applications",
   "license": "MIT",
   "scripts": {
-    "postinstall": "node ./src/createEslintStylisticConfig.js",
     "tsc": "tsc",
     "oxlint": "oxlint",
     "oxlint-fix": "oxlint --fix",
@@ -16,30 +18,43 @@
   },
   "dependencies": {
     "@minify-html/node": "^0.18.1",
-    "@newlogic-digital/vite-plugin-heroicons": "^1.1.0",
+    "@newlogic-digital/vite-plugin-heroicons": "^1.1.1",
     "@stylistic/eslint-plugin": "^5.10",
     "@stylistic/stylelint-config": "^4.0.0",
-    "@vituum/vite-plugin-css-inline": "^2.0.0",
-    "@vituum/vite-plugin-latte": "^2.0.0",
-    "@vituum/vite-plugin-send": "^2.0.0",
+    "@vituum/vite-plugin-css-inline": "^2.0.2",
+    "@vituum/vite-plugin-latte": "^2.0.2",
+    "@vituum/vite-plugin-send": "^2.0.1",
     "browserslist": "^4.28.1",
     "browserslist-to-esbuild": "^2.1.1",
     "lightningcss": "^1.32.0",
+    "npm-check-updates": "^19.6.5",
     "oxlint": "^1.56.0",
     "stylelint-config-standard": "^40.0.0",
-    "vituum": "^2.0.0"
+    "vituum": "^2.0.1"
+  },
+  "peerDependencies": {
+    "@tailwindcss/vite": "4.2.2",
+    "@vituum/vite-plugin-twig": "^2.0.1",
+    "vite": "^8.0.1"
+  },
+  "peerDependenciesMeta": {
+    "@vituum/vite-plugin-twig": {
+      "optional": true
+    },
+    "@tailwindcss/vite": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "@tailwindcss/vite": "0.0.0-insiders.d24b112",
     "@types/node": "^25.5",
-    "@vituum/vite-plugin-twig": "^2.0.0",
-    "rolldown": "^1.0.0-rc.9",
-    "typescript": "^5",
-    "vite": "^8.0.0"
+    "rolldown": "^1.0.0-rc.10",
+    "typescript": "^5"
   },
   "files": [
+    "bin",
     "icons",
     "latte",
+    "skills",
     "src",
     "types",
     "eslint-stylistic.json",

package/skills/figma-implement-design/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: figma-implement-design
+description: Translate Figma nodes into production-ready code with 1:1 visual fidelity using the Figma MCP workflow (design context, screenshots, assets, and project-convention translation). Trigger when the user provides Figma URLs or node IDs, or asks to implement designs or components that must match Figma specs. Requires a working Figma MCP server connection.
+---
+
+# Implement Design
+
+## Overview
+
+This skill provides a structured workflow for translating Figma designs into production-ready code with pixel-perfect accuracy. It ensures consistent integration with the Figma MCP server, proper use of design tokens, and 1:1 visual parity with designs.
+
+## Prerequisites
+
+- Figma MCP server must be connected and accessible
+- User must provide a Figma URL in the format: `https://figma.com/design/:fileKey/:fileName?node-id=1-2`
+    - `:fileKey` is the file key
+    - `1-2` is the node ID (the specific component or frame to implement)
+- **OR** when using `figma-desktop` MCP: User can select a node directly in the Figma desktop app (no URL required)
+- Project should have an established design system or component library (preferred)
+
+### Step 1: Get Node ID
+
+#### Option A: Parse from Figma URL
+
+When the user provides a Figma URL, extract the file key and node ID to pass as arguments to MCP tools.
+
+**URL format:** `https://figma.com/design/:fileKey/:fileName?node-id=1-2`
+
+**Extract:**
+
+- **File key:** `:fileKey` (the segment after `/design/`)
+- **Node ID:** `1-2` (the value of the `node-id` query parameter)
+
+**Note:** When using the local desktop MCP (`figma-desktop`), `fileKey` is not passed as a parameter to tool calls. The server automatically uses the currently open file, so only `nodeId` is needed.
+
+**Example:**
+
+- URL: `https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15`
+- File key: `kL9xQn2VwM8pYrTb4ZcHjF`
+- Node ID: `42-15`
+
+#### Option B: Use Current Selection from Figma Desktop App (figma-desktop MCP only)
+
+When using the `figma-desktop` MCP and the user has NOT provided a URL, the tools automatically use the currently selected node from the open Figma file in the desktop app.
+
+**Note:** Selection-based prompting only works with the `figma-desktop` MCP server. The remote server requires a link to a frame or layer to extract context. The user must have the Figma desktop app open with a node selected.
+
+### Step 2: Fetch Design Context
+
+Run `get_design_context` with the extracted file key and node ID.
+
+```
+get_design_context(fileKey=":fileKey", nodeId="1-2")
+```
+
+This provides the structured data including:
+
+- Layout properties (Auto Layout, constraints, sizing)
+- Typography specifications
+- Color values and design tokens
+- Component structure and variants
+- Spacing and padding values
+
+**If the response is too large or truncated:**
+
+1. Run `get_metadata(fileKey=":fileKey", nodeId="1-2")` to get the high-level node map
+2. Identify the specific child nodes needed from the metadata
+3. Fetch individual child nodes with `get_design_context(fileKey=":fileKey", nodeId=":childNodeId")`
+4. Run `get_variable_defs(fileKey=":fileKey", nodeId="1-2")` to get the variable definitions for the child nodes
+
+### Step 3: Resolve Code Connect Mappings
+
+Run `get_code_connect_map` on the same top-level node before implementation starts.
+
+```
+get_code_connect_map(fileKey=":fileKey", nodeId="1-2")
+```
+
+This step is mandatory for a correct design-system handoff.
+
+**Interpretation rules:**
+
+- If `nodeId="1-2"` is a page, frame, or large section, treat the returned map as the authoritative list of mapped descendant components that MUST be preserved in the final handoff.
+- Do NOT assume the explicit `CodeConnectSnippet` wrappers shown in `get_design_context` are the full list. A page-level `get_code_connect_map` may return many more mapped descendants.
+- `CodeConnectSnippet` wrapper elements are never part of final code. Use only the inner snippet or the actual mapped component in the codebase.
+- Do NOT rename Code Connect classes, collapse modifier classes into new aliases, or replace mapped snippet APIs with custom helper classes just because the implementation is standalone or the classes do not exist yet. Implement the missing styles behind the mapped contract instead.
+- If you must diverge from the mapped markup or class API for technical reasons, STOP and get explicit user approval first. Explain the exact incompatibility and the minimal required deviation.
+
+### Step 3: Capture Visual Reference
+
+Run `get_screenshot` with the same file key and node ID for a visual reference.
+
+```
+get_screenshot(fileKey=":fileKey", nodeId="1-2")
+```
+
+This screenshot serves as the source of truth for visual validation. Keep it accessible throughout implementation.
+
+### Step 4: Download Assets
+
+Download any assets (images, icons, SVGs) returned by the Figma MCP server, BUT ONLY if the user specifically asks, otherwise skip this step.
+
+**IMPORTANT:** Follow these asset rules:
+
+- NEVER invent, redraw, approximate, reconstruct, or substitute assets that already exist in the Figma payload. If Figma provides an icon, SVG, image, or vector, use that original asset or exact markup. If you are about to replace an existing asset ALWAYS STOP AND ASK the user first.
+- If the original Figma code already contains the asset markup, preserve or translate that exact asset instead of recreating it by hand.
+- Assets are served through the Figma MCP server's built-in assets endpoint
+- If the user or other skill specifies to use placeholder assets, or icon packs, follow the provided guidelines and do NOT use figma assets.
+- If an asset URL or payload cannot be consumed in the target runtime, treat that as a blocker for exact fidelity. Report the failure clearly and ask the user before recreating, approximating, or substituting the asset.
+
+### Step 5: Translate to Project Conventions
+
+Translate the Figma output into this project's framework, styles, and conventions.
+
+**Key principles:**
+
+- Treat the Figma MCP output (typically React + Tailwind) as a representation of design and behavior, not as final code style
+- Treat Code Connect mappings as authoritative handoff requirements, not optional hints
+- Review that the Tailwind utility classes are using the latest Tailwind conventions and patterns (MUST be version 4 and above)
+- Always use Tailwind CSS v4. If the project does not already have a Tailwind build pipeline, use the browser build from `https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4`. Do NOT use the legacy `https://cdn.tailwindcss.com` script.
+- Reuse existing components (buttons, inputs, typography, icon wrappers) instead of duplicating functionality
+- Search the codebase for mapped component sources before falling back to raw snippets
+- Use the project's color system, typography scale, and spacing tokens consistently
+- Respect existing routing, state management, and data-fetch patterns
+- Preserve the original Figma layout and DOM structure as closely as possible. Do NOT redesign, simplify, restructure, or "improve" the layout unless responsiveness, technical constraints, or an explicit user request requires it.
+- Responsiveness is the default exception: adapt layout only as much as needed for smaller breakpoints while keeping the desktop structure faithful to the original frame.
+- If you are about to make a large structural change, invent missing structure, or replace original layout patterns with new ones, STOP and ASK the user first.
+- If Code Connect provides raw HTML class contracts instead of framework components, preserve those contracts in the final output. Add CSS/Tailwind support for them if needed, but do not silently translate them into a different API.
+
+### Step 6: Achieve 1:1 Visual Parity
+
+Strive for pixel-perfect visual parity with the Figma design.
+
+**Guidelines:**
+
+- Prioritize Figma fidelity to match designs exactly
+- Avoid hardcoded values - use design tokens from Figma where available
+- When conflicts arise between design system tokens and Figma specs, prefer design system tokens but adjust spacing or sizes minimally to match visuals
+- Follow WCAG requirements for accessibility
+- Add component documentation as needed
+
+### Step 7: Validate Against Figma
+
+Before marking complete, validate the final UI against the Figma screenshot.
+
+**Validation checklist:**
+
+- [ ] Layout matches (spacing, alignment, sizing)
+- [ ] Typography matches (font, size, weight, line height)
+- [ ] Colors match exactly
+- [ ] Interactive states work as designed (hover, active, disabled)
+- [ ] Responsive behavior follows Figma constraints
+- [ ] Assets render correctly
+- [ ] Every descendant returned by `get_code_connect_map` on the top-level node is represented in the final code
+- [ ] Accessibility standards met
+
+### Step 8: Validate Against Browser
+
+Use the /agent-browser skill if exists to validate the final UI in the browser. 
+
+- If the skill does not exist, skip this step.
+- If the skill command fails, ask the user to manually validate the UI in the browser and skip this step.
+
+## Implementation Rules
+
+### Component Organization
+
+- Place UI components in the project's designated design system directory
+- Follow the project's component naming conventions
+- Avoid inline styles unless truly necessary for dynamic values
+
+### Design System Integration
+
+- ALWAYS use components from the project's design system when possible
+- ALWAYS preserve mapped Code Connect components in the final handoff when they exist
+- When using mapped Code Connect snippets directly, preserve their public contract exactly: same tags, same classes, same attributes, same variant/modifier naming.
+- Map Figma design tokens to project design tokens
+- When a matching component exists, extend it rather than creating a new one
+- Document any new components added to the design system
+- If any workaround would change assets, mapped component contracts, markup structure, or visual composition in a way that is not explicitly present in Figma, STOP and get user approval first.
+
+## Examples
+
+### Example 1: Implementing a Button Component
+
+User says: "Implement this Figma button component: https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15"
+
+**Actions:**
+
+1. Parse URL to extract fileKey=`kL9xQn2VwM8pYrTb4ZcHjF` and nodeId=`42-15`
+2. Run `get_design_context(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42-15")` and `get_code_connect_map(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42-15")`
+3. Run `get_screenshot(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42-15")` for visual reference
+4. Download any button icons from the assets endpoint
+5. Check if project has existing button component
+6. If yes, extend it with new variant; if no, create new component using project conventions
+7. Map Figma colors to project design tokens (e.g., `primary-500`, `primary-hover`)
+8. Validate against screenshot for padding, border radius, typography
+
+**Result:** Button component matching Figma design, integrated with project design system.
+
+### Example 2: Building a Dashboard Layout
+
+User says: "Build this dashboard: https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Dashboard?node-id=10-5"
+
+**Actions:**
+
+1. Parse URL to extract fileKey=`pR8mNv5KqXzGwY2JtCfL4D` and nodeId=`10-5`
+2. Run `get_metadata(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10-5")` to understand the page structure
+3. Identify main sections from metadata (header, sidebar, content area, cards) and their child node IDs
+4. Run `get_design_context(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId=":childNodeId")` and `get_code_connect_map(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId=":childNodeId")` for each major section
+5. Run `get_screenshot(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10-5")` for the full page
+6. Download all assets (logos, icons, charts)
+7. Build layout using project's layout primitives
+8. Implement each section using existing components where possible
+9. Validate responsive behavior against Figma constraints
+
+### Code Quality
+
+- Avoid hardcoded values - extract to constants or design tokens
+- Keep components composable and reusable
+
+## Best Practices
+
+### Always Start with Context
+
+Never implement based on assumptions. Always fetch `get_design_context`, `get_code_connect_map` and `get_screenshot` first.
+
+### Original Assets First
+
+If Figma already provides an asset, vector, or exact SVG/code representation, use that original source. Do NOT redraw icons, invent substitute artwork, or replace provided assets with lookalikes.
+
+### Incremental Validation
+
+Validate frequently during implementation, not just at the end. This catches issues early.
+
+### Ask Before Large Inventions
+
+If the implementation required inventing significant structure, changing layout patterns, or making large visual/architectural decisions that were not explicitly requested, STOP and ask the user before proceeding.
+
+### Reuse Over Recreation
+
+Always check for existing components before creating new ones. Consistency across the codebase is more important than exact Figma replication.
+
+### Design System First
+
+When in doubt, prefer the project's design system patterns over literal Figma translation.

package/skills/figma-implement-design/agents/openai.yaml

@@ -0,0 +1,14 @@
+interface:
+  display_name: "Figma Implement Design"
+  short_description: "Turn Figma designs into production-ready code"
+  icon_small: "./assets/figma-small.svg"
+  icon_large: "./assets/figma.png"
+  default_prompt: "Implement this Figma design in this codebase, using mapped Code Connect components wherever available and matching layout, states, and responsive behavior."
+
+dependencies:
+  tools:
+    - type: "mcp"
+      value: "figma"
+      description: "Figma MCP server"
+      transport: "streamable_http"
+      url: "https://mcp.figma.com/mcp"

package/skills/figma-implement-design/assets/figma-small.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16">
+  <path fill="#000" fill-rule="evenodd" d="M4.994 5.986a2.014 2.014 0 1 0 0 4.028h2.069V5.986H4.994Zm5.063-.98h.055a2.014 2.014 0 1 0 0-4.026h-2.07v4.027h2.015Zm1.697.49A2.994 2.994 0 0 0 10.112 0H4.994a2.994 2.994 0 0 0-1.642 5.498A2.99 2.99 0 0 0 2 8a2.99 2.99 0 0 0 1.352 2.503A2.99 2.99 0 0 0 2 13.007C2 14.663 3.358 16 5.008 16c1.665 0 3.035-1.349 3.035-3.02v-2.765a2.984 2.984 0 0 0 2.014.778h.055a2.994 2.994 0 0 0 1.642-5.496Zm-1.642.49h-.055a2.014 2.014 0 1 0 0 4.028h.055a2.014 2.014 0 1 0 0-4.028Zm-7.132 7.02c0-1.111.902-2.013 2.014-2.013h2.069v1.987c0 1.123-.924 2.04-2.055 2.04a2.026 2.026 0 0 1-2.028-2.013Zm4.083-8H4.994a2.014 2.014 0 1 1 0-4.026h2.069v4.027Z" clip-rule="evenodd"/>
+</svg>

package/skills/figma-implement-design/assets/icon.svg

@@ -0,0 +1,28 @@
+<svg
+  width="400"
+  height="400"
+  viewBox="0 0 400 400"
+  fill="none"
+  xmlns="http://www.w3.org/2000/svg"
+>
+  <path
+    d="M97.5 302.5C97.5 274.195 120.445 251.25 148.75 251.25H200V302.5C200 330.805 177.055 353.75 148.75 353.75C120.445 353.75 97.5 330.805 97.5 302.5Z"
+    fill="#0ACF83"
+  />
+  <path
+    d="M200 200C200 171.696 222.945 148.75 251.25 148.75C279.554 148.75 302.5 171.695 302.5 200C302.5 228.305 279.554 251.25 251.25 251.25C222.945 251.25 200 228.304 200 200Z"
+    fill="#1ABCFE"
+  />
+  <path
+    d="M97.5 200C97.5 228.305 120.445 251.25 148.75 251.25H200V148.75H148.75C120.445 148.75 97.5 171.695 97.5 200Z"
+    fill="#A259FF"
+  />
+  <path
+    d="M200 46.25V148.75H251.25C279.555 148.75 302.5 125.805 302.5 97.5C302.5 69.1954 279.555 46.25 251.25 46.25H200Z"
+    fill="#FF7262"
+  />
+  <path
+    d="M97.5 97.5C97.5 125.805 120.445 148.75 148.75 148.75H200V46.25L148.75 46.25C120.445 46.25 97.5 69.1954 97.5 97.5Z"
+    fill="#F24E1E"
+  />
+</svg>

package/skills/newlogic-ui/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: newlogic-ui
+description: This skill provides repo-specific rules for LLM agents working with the Newlogic UI framework. Use it for UI, components, layouts, styles, responsiveness, frontend logic, and design implementation in this repository.
+---
+
+# Newlogic UI Skill
+
+ALWAYS load `https://ui.newlogic.cz/llms-full.txt` before making changes in this framework.
+
+ALWAYS read ALL local guides in `references/` before starting work. These guides are intentionally short and contain ONLY repo-specific rules that override, narrow, or clarify `llms-full.txt`.
+
+## Source Priority
+
+Use this priority order when rules differ:
+
+1. Existing files in this repository
+2. Local guides in this skill
+3. `https://ui.newlogic.cz/llms-full.txt`
+
+## Working Rule
+
+Use `llms-full.txt` for framework behavior, available components, and implementation examples.
+
+Use the local guides for repository conventions that MUST be followed even if a generic example from `llms-full.txt` suggests another valid approach.
+
+## Required Guides
+
+- [Project Guide](references/project-guide.md) - naming, structure, and placement rules
+- [Assets Guide](references/assets-guide.md) - placeholder, image, and icon rules
+- [Templating Guide](references/templating-guide.md) - Latte and JSON data rules for this repo
+- [Styling Guide](references/styling-guide.md) - local CSS and component styling constraints
+- [Theme Guide](references/theme-guide.md) - local theme token and theme file rules
+- [Scripting Guide](references/scripting-guide.md) - local JS and Stimulus placement rules

package/skills/newlogic-ui/references/assets-guide.md

@@ -0,0 +1,126 @@
+# Assets Guide
+
+## Images
+
+- Do NOT use assets from Figma unless the user explicitly asks for them.
+- Instead, use the placeholder images below.
+- For placeholder images use https://placehold.co/ (preferred by default) or https://picsum.photos/.
+- NEVER reinvent or reconstruct the images from scratch. Either use a placeholder image as `img` or a Figma asset as `img`.
+- Most content images SHOULD use the `x-image` wrapper.
+- Put the aspect ratio utility on the `<img>` element, NOT on the wrapper.
+- Transparent images SHOULD NOT use the `x-image` wrapper.
+
+**Preferred markup:**
+
+```html
+<div class="x-image before:skeleton">
+    <img class="aspect-4/3" src="https://placehold.co/800x600" loading="lazy" alt="">
+</div>
+```
+
+**Transparent image markup:**
+
+```html
+<img class="aspect-3/2" src="https://placehold.co/300x200" loading="lazy" alt="">
+```
+
+## Icons
+
+- ALWAYS use SVG for icons.
+- Prefer `<use>` for reusable icons.
+- If adding reusable outline icons, place them in `src/icons/outline/`.
+- If adding reusable solid icons, place them in `src/icons/solid/`.
+- Brand icons are available in `src/icons/simpleicons/`.
+- Heroicons are already available through the build setup, so do NOT duplicate them in `src/icons/`.
+- The `<use href="...">` symbol definitions are generated automatically by the build setup.
+- Icon IDs SHOULD generally follow Figma naming when possible.
+- Inline `<svg>` without `<use>` is allowed ONLY for one-off icons that will NOT be reused.
+
+**Reusable icon examples:**
+
+```html
+<svg class="size-6">
+    <use href="#icons-outline/hello"></use>
+</svg>
+```
+
+```html
+<svg class="size-6">
+    <use href="#simpleicons-solid/facebook"></use>
+</svg>
+```
+
+```html
+<svg class="size-6">
+    <use href="#heroicons-outline/academic-cap"></use>
+</svg>
+```
+
+### Icon Strategy Summary
+
+1. Heroicons via `<use href="#heroicons-*/*">`
+2. Project reusable icons via `src/icons/outline`, `src/icons/solid`, or `src/icons/simpleicons`
+3. Inline `<svg>` without `<use>` for one-off icons ONLY
+
+## Example
+You are about to translate the Figma output into this project.
+
+### Step 1 – Figma handoff
+- Figma output provide provides assets like this `<img alt="" className="absolute block max-w-none size-full" src={imgVector}` 
+- with urls like this https://www.figma.com/api/mcp/asset/557d8c1d-efe3-42ad-bccb-e5db8ebd14e6
+- You succefully identified a type of the asset as `image` or `icon` from the Figma output.
+
+### Step 2 – Image
+- You check the width and height of the image and decide if it is transparent or not.
+
+#### If the user didn't ask to use Figma assets
+- In this case you will use the placeholder image.
+- You will use the correct width and height and aspect ratio.
+
+```html
+<div class="x-image before:skeleton">
+    <img class="aspect-4/3" src="https://placehold.co/800x600" loading="lazy" alt="">
+</div>
+```
+
+- If the image is transparent, you will use the following markup without the `x-image` wrapper:
+
+```html
+<img class="aspect-3/2" src="https://placehold.co/300x200" loading="lazy" alt="">
+```
+
+#### If the user explicitly asks to use Figma assets
+
+- You downloaded the image from Figma and placed it in `src/assets/images`.
+- You renamed the image to match the Figma asset name.
+- You updated the markup to use the new image path.
+- You will use the correct width and height and aspect ratio.
+
+```html
+<div class="x-image before:skeleton">
+    <img class="aspect-4/3" src="/src/assets/my-new-image.jpg" loading="lazy" alt="">
+</div>
+```
+
+### Step 2 – Icon
+- You check the width and height of the icon and decide if it is a brand icon, heroicon or other icon.
+
+- If you identify the icon as a brand icon, you will check if it is already available in `src/icons/simpleicons`.
+- If it is not available, you will add it to `src/icons/simpleicons`.
+- If it is available, you will use the existing icon.
+- You will use the following markup in the HTML:
+
+```html
+<svg class="size-6">
+    <use href="#simpleicons-solid/facebook"></use>
+</svg>
+```
+
+- If you identify the icon as a heroicon, you will match the figma name to the heroicon name.
+- You will use the following markup in the HTML:
+```html
+<svg class="size-6">
+    <use href="#heroicons-outline/academic-cap"></use>
+</svg>
+```
+

package/skills/newlogic-ui/references/project-guide.md

@@ -0,0 +1,25 @@
+# Project Guide
+
+## Naming
+
+- Use PascalCase for component files such as `Button.latte`, `HeroSection.latte`, `Reveal.js`, `Header.css`.
+- Use kebab-case with `x-` prefix for component classes such as `x-button`, `x-hero-section`.
+- ALWAYS check if the component class name matches the file name, e.g. `HeroSection.latte` and `x-hero-section` matches
+- ALWAYS keep one primary `x-*` component per file.
+- Use kebab-case for generic utility files such as `format-date.js` or `scrollbar.css`.
+
+## Placement
+
+- Latte components belong in `src/templates/components/`.
+- UI component templates belong in `src/templates/components/(ui)/` when they are reusable UI building blocks.
+- Section or layout groupings MAY use parentheses directories such as `(sections)` or `(layout)`.
+- Component CSS belongs in `src/styles/components/`.
+- Winduum-based UI component CSS belongs in `src/styles/components/(ui)/`.
+- Component scripts belong in `src/scripts/components/`.
+- Winduum-based UI controllers belong in `src/scripts/components/(ui)/`.
+
+## Structure
+
+- Match template, style, and script names when the same component exists across layers.
+- Keep the repo structure aligned with existing files before introducing a new folder or naming pattern.
+- If a pattern already exists in nearby files, ALWAYS follow that pattern instead of inventing a parallel one.

package/skills/newlogic-ui/references/scripting-guide.md

@@ -0,0 +1,38 @@
+# Scripting Guide
+
+## Placement
+
+- Entry point is `src/scripts/main.js`.
+- Shared setup belongs in `src/scripts/composables/`.
+- Reusable helpers belong in `src/scripts/utils/`.
+- Custom component controllers belong in `src/scripts/components/`.
+- Winduum-based UI controllers belong in `src/scripts/components/(ui)/`.
+
+## Local Rules
+
+- Use modern plain JS that matches the existing codebase.
+- Register one primary controller per file.
+- Keep controller names aligned with existing `x-*` naming in this repo.
+- If dynamic HTML is inserted into the DOM, ALWAYS re-initialize it with `src/scripts/utils/initAfter.js`.
+- Follow the existing import aggregation pattern with `+.js` files when adding new controllers to an existing folder.
+
+**Local `initAfter` import pattern:**
+
+```javascript
+import { initAfter } from '../utils/+.js'
+
+initAfter(document.querySelector('.newlyAppendedContent'))
+```
+
+**Aggregator pattern:**
+
+```javascript
+// src/scripts/components/(ui)/+.js
+import './Button.js'
+import './Dialog.js'
+```
+
+## Before Adding JS
+
+- Prefer existing Winduum, Stimulus, or utility behavior from `llms-full.txt` before creating new custom JS.
+- Do NOT introduce a second interaction pattern if the repo already has an established controller for the same problem.

package/skills/newlogic-ui/references/styling-guide.md

@@ -0,0 +1,75 @@
+# Styling Guide
+
+## General
+
+- ALWAYS prefer Tailwind utilities before writing custom CSS.
+- Use custom CSS for defaults, complex states, or component-specific behavior that should NOT live in templates.
+- Follow nearby files before introducing a new styling pattern.
+- Prefer responsive utilities such as `sm:`, `md:`, and `lg:` in templates. Use `@custom-media` only when writing custom CSS.
+
+**Custom breakpoint example:**
+
+```css
+.my-component {
+    padding: 1rem;
+
+    @media (--media-lg) {
+        padding: 2rem;
+    }
+}
+```
+
+## UI Components
+
+- Winduum-based UI components live in `src/styles/components/(ui)/`.
+- UI component defaults belong in their CSS files, NOT in template utility piles.
+- Define base sizing, padding, radius, font defaults, and default colors in CSS for UI components.
+- In templates, only small layout utilities are allowed on UI components, such as width, flex, gap, order, or spacing adjustments.
+- Do NOT redefine a UI component's base look directly in templates.
+- Do NOT restyle existing `x-*` UI components from a large level CSS file when the change is really a button, badge, control, field, pagination, or other UI-component concern.
+- If a Figma page introduces a new shared UI look, extend the relevant file in `src/styles/components/(ui)/` instead of creating specific overrides from a parent component for that component.
+
+## Non-UI Components
+
+- Regular non-UI components SHOULD be styled entirely with Tailwind utilities in the template by default.
+- For non-UI components, prefer Tailwind even when the template gets longer. A longer utility-based template is still preferred over creating component CSS too early.
+- Create component CSS for non-UI components ONLY when there is styling logic that genuinely should not live in the template, such as complex selectors, state relationships, pseudo-element composition, browser-specific behavior, or similarly non-trivial logic that cannot be expressed cleanly with Tailwind utilities alone.
+- Do NOT create component CSS just to group utilities, shorten markup, or move ordinary layout/spacing/typography rules out of the template.
+- Treat non-UI component CSS as a true last resort. It should be used only in genuinely exceptional cases, not as a convenience or organizational preference.
+- If a non-UI component reaches that exceptional threshold and needs CSS, follow the `data-part` pattern for internal styling instead of inventing extra internal class names.
+- Avoid large level CSS files that absorb layout, typography, and UI and other component styling at the same time. If a page file starts becoming the source of truth for `x-*` components, move that logic back into `(ui)` CSS and keep the page mostly utility-driven.
+
+## Tokens And Units
+
+- ALWAYS use theme tokens such as `text-primary`, `bg-main`, or `text-body-foreground` before raw color values.
+- If the design needs a new default token, update `src/styles/theme/main.css`.
+- Do NOT use `px` units, except `1px` or `2px` borders when needed.
+
+## Component Parts
+
+- This section applies primarily to non-UI components when CSS is truly unavoidable.
+- Use `data-part` for stylable internal parts.
+- Do NOT create extra part class names such as `x-card-header` or `x-hero-content` when `data-part` is sufficient.
+- For non-UI components, `data-part` is the required internal styling pattern whenever an exceptional CSS case is justified.
+
+**Preferred part pattern:**
+
+```html
+<div class="x-my-component">
+    <div data-part="header">...</div>
+    <div data-part="content">...</div>
+</div>
+```
+
+```css
+.x-my-component {
+    [data-part="header"] {
+        /* complex styles */
+    }
+}
+```
+
+## Winduum Extensions
+
+- Inspect the imported Winduum files in the component CSS to see which custom properties are available.
+- Extend Winduum components through their existing imports and local CSS layers instead of re-implementing them from scratch.

package/skills/newlogic-ui/references/templating-guide.md

@@ -0,0 +1,106 @@
+# Templating Guide
+
+## Layout
+
+- Use `src/templates/layouts/default.latte` unless the user explicitly asks for another layout.
+- Do NOT create a custom layout when the default layout already supports the change.
+
+## Data Sources
+
+- Global data lives in `src/data/main.json`.
+- In this repo, global layout sections are typically defined through `head` and `foot` arrays in `src/data/main.json`.
+- Page data lives in `src/pages/*.json` and inherits global data.
+- Section rendering is handled through `src/templates/utils/sections.latte`.
+- Components referenced from page JSON are passed as `$control`.
+- In this repo, `src/pages/*.json` is the composition layer for whole pages. Prefer assembling a page there instead of creating a wrapper `*Page.latte` component that just nests the entire page structure.
+- Preserve the existing `head` and `foot` layout structure unless the user explicitly asks to change the layout contract.
+- If a Figma page includes a site header or site footer, implement those designs in the existing `components/header/Header.latte` and `components/footer/Footer.latte` flow rather than moving them into `body`.
+
+**Global layout data example:**
+
+```json
+{
+  "head": [
+    { "src": "components/header/Header.latte" }
+  ],
+  "foot": [
+    { "src": "components/footer/Footer.latte" }
+  ]
+}
+```
+
+**Layout asset access example:**
+
+```latte
+<link n:foreach="$assets->css->all as $url" href="{$url|asset}" rel="stylesheet">
+<script src="{$assets->js->main|asset}" type="module"></script>
+```
+
+## JSON Rules
+
+- Do NOT store CSS class strings in JSON.
+- JSON should contain semantic values and content, NOT presentation classes.
+- If a template depends on an optional flag such as `active`, `dropdown`, or variant switches, define that flag explicitly in JSON.
+- Keep repeated global UI data in `src/data/main.json` rather than duplicating it across page JSON files.
+
+## Latte Rules
+
+- Prefer direct access to existing variables such as `$control` and global layout data.
+- Keep ad hoc `{var ...}` usage to a minimum.
+- Use `{default}` for optional fallback values when needed.
+- Do NOT combine `class` and `n:class` on the same element. Use one `n:class` expression that includes the base classes.
+
+**`n:class` pattern:**
+
+```latte
+<a n:class="'base classes ' . ($isActive ? 'active' : 'idle')">Link</a>
+```
+
+**`{default}` pattern:**
+
+```latte
+{default $disabled = false}
+```
+
+## Components
+
+- Put reusable page sections in `src/templates/components/`.
+- Keep component file names in PascalCase.
+- If a component is rendered from page JSON, assume `$control` is the primary input object unless the existing local pattern clearly does something else.
+- Match the current folder conventions such as `(sections)`, `(ui)`, `header/`, `footer/`, `dialog/`, or `cookieconsent/` before introducing a new grouping.
+- Do NOT create a monolithic page wrapper component when the page can be expressed as multiple body sections in JSON.
+- Prefer one component per visible section or repeated block, then compose those sections from `src/pages/*.json`.
+- If an existing component already matches the Figma element, reuse that component instead of creating a specific duplicate.
+- If a Figma element maps to an existing `(ui)` component such as `Pagination.latte`, `Button`, `Dialog`, `Toast`, or similar, extend that existing component if needed; do NOT create parallel specific versions like `ArticlesPagination.latte` unless the user explicitly asks for a separate component.
+
+**Page JSON to component flow:**
+
+```json
+{
+  "body": [
+    {
+      "src": "components/HeroSection.latte",
+      "heading": "Welcome",
+      "buttonText": "Get Started"
+    }
+  ]
+}
+```
+
+```latte
+{foreach $sections as $section}
+    {include ('../' . $section->src), control => $section}
+{/foreach}
+```
+
+```latte
+<section class="x-hero-section">
+    <h1 n:if="isset($control->heading)">{$control->heading}</h1>
+</section>
+```
+
+**Direct include pattern:**
+
+```latte
+{include 'components/Button.latte', text: 'Click me'}
+```

package/skills/newlogic-ui/references/theme-guide.md

@@ -0,0 +1,23 @@
+# Theme Guide
+
+## Theme Files
+
+- Main website theme tokens live in `src/styles/theme/main.css`.
+- Keep website theme defaults in `@theme`.
+- Extend the existing token system before inventing component-local hardcoded values.
+
+## Local Rules
+
+- ALWAYS prefer semantic tokens over raw values in templates and components.
+- If the design introduces a new shared color, spacing, or layout default, add or adjust the token in `src/styles/theme/main.css`.
+- Reuse existing tokens such as `primary`, `main`, `body`, and status colors before creating new ones.
+- Keep theme changes centralized instead of scattering hardcoded values across multiple component files.
+
+**Common token usage:**
+
+```html
+<div class="bg-primary text-primary-foreground">Primary Button</div>
+<div class="bg-main text-main-foreground">Dark Section</div>
+<div class="max-w-(--container-width)">Constrained content</div>
+<div class="x-button accent-main">Primary text</div>
+```

package/src/linkAgentSkills.js

@@ -0,0 +1,107 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { styleText } from 'node:util'
+import { fileURLToPath } from 'node:url'
+import { getPackageInfo } from 'vituum/utils/common.js'
+
+const IS_WIN32 = process.platform === 'win32'
+const { name } = getPackageInfo(new URL('../package.json', import.meta.url).href)
+const scriptDir = path.dirname(fileURLToPath(import.meta.url))
+const packageRoot = path.resolve(scriptDir, '..')
+const sourceSkillsDir = path.join(packageRoot, 'skills')
+const projectRoot = process.env.INIT_CWD ? path.resolve(process.env.INIT_CWD) : null
+
+function isSameSymlinkTarget(targetPath, expectedSourcePath) {
+  const currentTarget = fs.readlinkSync(targetPath)
+  const resolvedTarget = path.resolve(path.dirname(targetPath), currentTarget)
+
+  return resolvedTarget === expectedSourcePath
+}
+
+function getExistingTargetStat(targetPath) {
+  try {
+    return fs.lstatSync(targetPath)
+  }
+  catch (error) {
+    if (error?.code === 'ENOENT') {
+      return null
+    }
+
+    throw error
+  }
+}
+
+function createDirectorySymlink(sourcePath, targetPath) {
+  const symlinkTarget = IS_WIN32
+    ? sourcePath
+    : path.relative(path.dirname(targetPath), sourcePath)
+  const symlinkType = IS_WIN32 ? 'junction' : 'dir'
+
+  fs.symlinkSync(symlinkTarget, targetPath, symlinkType)
+}
+
+if (!projectRoot || projectRoot === packageRoot || !fs.existsSync(sourceSkillsDir)) {
+  process.exit(0)
+}
+
+const targetAgentsDir = path.join(projectRoot, '.agents')
+const targetSkillsDir = path.join(targetAgentsDir, 'skills')
+const targetClaudePath = path.join(projectRoot, '.claude')
+const skillEntries = fs.readdirSync(sourceSkillsDir, { withFileTypes: true })
+  .filter(entry => entry.isDirectory())
+
+if (skillEntries.length === 0) {
+  process.exit(0)
+}
+
+fs.mkdirSync(targetSkillsDir, { recursive: true })
+
+let linkedCount = 0
+let linkedClaudeDir = false
+
+for (const entry of skillEntries) {
+  const sourcePath = path.join(sourceSkillsDir, entry.name)
+  const targetPath = path.join(targetSkillsDir, entry.name)
+  const targetStat = getExistingTargetStat(targetPath)
+
+  if (targetStat) {
+    if (!targetStat.isSymbolicLink()) {
+      console.warn(`${styleText(['cyan', 'bold'], name)} ${styleText('yellow', `Skipping skill "${entry.name}" because "${targetPath}" already exists and is not a symlink.`)}`)
+      continue
+    }
+
+    if (isSameSymlinkTarget(targetPath, sourcePath)) {
+      continue
+    }
+
+    fs.unlinkSync(targetPath)
+  }
+
+  createDirectorySymlink(sourcePath, targetPath)
+  linkedCount += 1
+}
+
+const claudeStat = getExistingTargetStat(targetClaudePath)
+
+if (claudeStat) {
+  if (!claudeStat.isSymbolicLink()) {
+    console.warn(`${styleText(['cyan', 'bold'], name)} ${styleText('yellow', `Skipping ".claude" because "${targetClaudePath}" already exists and is not a symlink.`)}`)
+  }
+  else if (!isSameSymlinkTarget(targetClaudePath, targetAgentsDir)) {
+    fs.unlinkSync(targetClaudePath)
+    createDirectorySymlink(targetAgentsDir, targetClaudePath)
+    linkedClaudeDir = true
+  }
+}
+else {
+  createDirectorySymlink(targetAgentsDir, targetClaudePath)
+  linkedClaudeDir = true
+}
+
+if (linkedCount > 0) {
+  console.info(`${styleText(['cyan', 'bold'], name)} ${styleText('green', `Linked ${linkedCount} skill${linkedCount === 1 ? '' : 's'} into "${targetSkillsDir}".`)}`)
+}
+
+if (linkedClaudeDir) {
+  console.info(`${styleText(['cyan', 'bold'], name)} ${styleText('green', `Linked "${targetClaudePath}" to "${targetAgentsDir}".`)}`)
+}