create-flowmo 1.1.0 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-flowmo",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Scaffold an OutSystems-Lite project with screens, data, logic, and built-in agent skills",
   "type": "module",
   "license": "MIT",

package/skills/outsystems-ui/SKILL.md

@@ -23,8 +23,10 @@ Build pixel-perfect OutSystems-compatible `.visual.html` prototypes using only t
 2. **12-column grid** — use `.columns2` through `.columns6` for responsive layouts. These auto-stack on mobile — do not add custom media queries.
 3. **No external JavaScript** — all interaction patterns are CSS/class-driven.
 4. **Layout is CRITICAL** — every screen MUST use one of the three OutSystems layouts. Pick the right one and use the exact HTML structure from the layout template files. The `.active-screen` wrapper is REQUIRED or utility classes will not resolve. See the **Layouts** section below.
-5. **Strip platform IDs** — never include `os-internal-id` or similar platform-generated attributes.
-6. **Widget slots** — use `{{content}}` placeholders in templates where nested widgets would go.
+5. **Scroll model** — OSUI sets `html { overflow: hidden }`. The `.active-screen` div is the actual scroll container. Your theme.css MUST include `.active-screen { overflow: hidden auto; height: 100vh; }` or the page will not scroll.
+6. **Strip platform IDs** — never include `os-internal-id` or similar platform-generated attributes.
+7. **Widget slots** — use `{{content}}` placeholders in templates where nested widgets would go.
+8. **theme.css is mandatory** — every project has a `theme.css` that loads after `outsystems-ui.css`. Use it for brand colors, custom component styles, and OSUI overrides. See the **Theme Customization** section below.
 
 ## Layouts
 
@@ -195,6 +197,30 @@ Add `.btn-loading` to the button and include a spinner element inside. This is C
 </button>
 ```
 
+### Button Specificity Warning
+
+The `.btn` class sets its own `color` and `background-color` with high specificity. **DO NOT** try to override button colors with OSUI color utilities like `.background-neutral-0` or `.text-primary` — they will be overridden by `.btn` rules and the text will become invisible.
+
+**Wrong** (text invisible — white on white):
+```html
+<button class="btn btn-primary background-neutral-0 text-primary">Open Account</button>
+```
+
+**Right** — use a named class in `theme.css`:
+```html
+<button class="btn hero-btn-primary">Open Account</button>
+```
+```css
+/* theme.css */
+.hero-btn-primary {
+  background: var(--bank-gold) !important;
+  color: var(--bank-navy) !important;
+  border: 2px solid var(--bank-gold) !important;
+}
+```
+
+If you need a button style that doesn't match `.btn-primary`, `.btn-cancel`, `.btn-success`, or `.btn-error`, create a custom class in `theme.css` rather than stacking conflicting utility classes.
+
 ## Borders
 
 ### Border Radius
@@ -334,23 +360,113 @@ Some patterns expose CSS custom properties for fine-tuning. Set these on the pat
 | Rating | `--rating-size: 16px` |
 | Scrollable Area | `--scrollable-area-width`, `--scrollable-area-height` |
 
+## Theme Customization
+
+Every project ships two CSS files: `outsystems-ui.css` (base framework) and `theme.css` (project overrides). The theme file loads second and extends OSUI.
+
+### What theme.css MUST contain
+
+1. **Scroll model fix** — OSUI expects `.active-screen` to be the scroll container:
+   ```css
+   .active-screen {
+     overflow: hidden auto;
+     height: 100vh;
+   }
+   ```
+
+2. **Brand tokens** — override `:root` CSS variables:
+   ```css
+   :root {
+     --color-primary: #1a56db;
+     --color-secondary: #0a1628;
+     --font-family-base: "Inter", -apple-system, BlinkMacSystemFont, sans-serif;
+   }
+   ```
+
+3. **Custom component classes** — for styles that can't be achieved with OSUI utilities alone (e.g. hero buttons, gradient backgrounds, themed footers). Use **BEM naming** (`block__element--modifier`):
+   ```css
+   .hero__btn--primary { ... }
+   .hero__btn--outline { ... }
+   .footer__link--active { ... }
+   .stats__number { ... }
+   .card__icon--large { ... }
+   ```
+   BEM keeps custom classes predictable and avoids collisions with OSUI's own class names.
+
+### What theme.css should NOT do
+
+- Don't redefine OSUI layout structure (`.layout`, `.main`, `.content`, `.header-content`)
+- Don't add `@media` queries — OSUI handles responsiveness
+- Don't override `.btn` base styles — create new named classes instead
+
+### Common OSUI specificity traps
+
+These OSUI classes set background/color with high specificity that utility classes can't override:
+
+| Class | Sets | Don't override with |
+|-------|------|--------------------|
+| `.btn` | `color`, `background-color` | `.text-*`, `.background-*` |
+| `.list-item` | `background-color: white` | Needs `background: transparent !important` in dark contexts |
+| `.card` | `background-color: white` | Needs explicit override for dark backgrounds |
+| `.badge` | `background-color`, `color` | Use `!important` or a custom class |
+
+### Icons
+
+OSUI does not bundle an icon font. If your screen uses Font Awesome icons (`<i class="fa fa-*">`), you MUST add the CDN link in `<head>`:
+
+```html
+<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css" />
+```
+
+Alternatively, use inline SVGs with the `.icon` class if you want to avoid external dependencies.
+
+### Dark section styling
+
+When placing content on a dark background (`.background-primary`, `.background-secondary`, or custom dark sections), remember:
+- Use `.text-neutral-0` for white text (headings, paragraphs)
+- Footer `.list-item` elements have `background: white` by default — override with `background: transparent !important`
+- Links default to the primary color — use custom classes for white/light link colors
+- Border colors may be invisible — use `border-color: rgba(255,255,255,0.1)` overrides
+
 ## Validation
 
 After generating a `.visual.html` file, verify:
-1. The root `<div>` has class `layout active-screen`
+1. The root `<div>` has class `active-screen` wrapping a `.layout` div
 2. No inline `style=""` attributes exist anywhere in the file
-3. All classes used are from the OSUI cheat sheet — no custom CSS class names
-4. The OSUI stylesheet `<link>` is present in `<head>`
-5. No `@media` queries or custom breakpoints were added
+3. All classes are either OSUI utilities OR custom classes defined in `theme.css` — no undefined classes
+4. Both `outsystems-ui.css` and `theme.css` stylesheet `<link>` tags are present in `<head>`
+5. If Font Awesome icons are used, the FA CDN `<link>` is in `<head>`
+6. No `@media` queries or custom breakpoints were added
+7. `.active-screen` scroll model is handled in `theme.css`
 
 If any check fails, fix the issue before presenting the output.
 
+### Visual testing with the dev server
+
+The project includes a Vite dev server. If `npm install` has already been run, start it with:
+
+```
+npm run dev
+```
+
+This serves all `.visual.html` files with hot-reload at `http://localhost:5173/`. Use it to:
+- **Open the page in a browser** and take a screenshot to verify the layout renders correctly
+- **Check for invisible text** — buttons or links with white-on-white or same-color text/background
+- **Confirm scrolling works** — the page should scroll within `.active-screen`
+- **Verify icons render** — Font Awesome icons should not be 0×0 invisible boxes
+- **Inspect computed styles** — confirm utility classes resolve as expected against OSUI
+
+Do NOT run `npm install` yourself — only use `npm run dev` if `node_modules` already exists.
+
 ## Gotchas
 
-- `.active-screen` class is **REQUIRED** on the layout wrapper `<div>`. Without it, utility classes and CSS variables will NOT resolve correctly.
+- `.active-screen` is **REQUIRED** as the outermost wrapper. Without it, utility classes and CSS variables will NOT resolve. It also serves as the **scroll container** — OSUI sets `html { overflow: hidden }` so `.active-screen` must have `overflow: hidden auto; height: 100vh` (set this in `theme.css`).
+- **Button + color utilities don't mix** — `.btn` overrides `color` and `background-color` at high specificity. Stacking `.btn .background-neutral-0 .text-primary` will produce invisible text (white on white). Create custom button classes in `theme.css` instead.
+- **`.list-item` has white background** — In dark-background sections (footer, sidebar), list items will show as white rectangles. Override with `background: transparent !important` in `theme.css`.
+- **Font Awesome is not bundled** — If using `<i class="fa fa-exchange">` style icons, add the FA 4.7 CDN link to `<head>` or the icons will be invisible (0×0 size).
 - OutSystems pattern previews render inside iframes — CSS resolves against the OSUI framework, not browser defaults. Your `.visual.html` must link the OSUI stylesheet.
-- **Never mix** inline `style=""` attributes with utility classes. Pick one approach — always prefer utility classes.
+- **Never mix** inline `style=""` attributes with utility classes. Always prefer utility classes.
 - `.columns*` patterns auto-stack on mobile breakpoints. Do NOT add custom `@media` queries to override this behavior.
 - Button loading state is purely CSS (`.btn-loading` + spinner element), not a JavaScript toggle.
 - Use `{{content}}` placeholders in component templates to indicate where nested child widgets go.
-- Always test your prototype with the OSUI CSS linked — plain browser rendering will look wrong.
+- Always generate BOTH the `.visual.html` AND corresponding `theme.css` styles together. A screen without proper theme styles will look broken.

package/template/theme/theme.css

@@ -3,6 +3,17 @@
    This file loads after outsystems-ui.css.
 ──────────────────────────────────────────────────────── */
 
+/* ── 1. OSUI scroll model ────────────────────────────
+   OSUI sets html { overflow: hidden }. The .active-screen
+   div is the actual scroll container for the page.
+   WITHOUT this rule, pages will not scroll.
+──────────────────────────────────────────────────────── */
+.active-screen {
+  overflow: hidden auto;
+  height: 100vh;
+}
+
+/* ── 2. Brand tokens ─────────────────────────────────── */
 :root {
   /* Brand colors – change these to match your app */
   --color-primary: #2979ff;
@@ -16,4 +27,7 @@
   --font-size-base: 14px;
 }
 
-/* Add your custom styles below */
+/* ── 3. Custom styles ────────────────────────────────── */
+/* Add custom component classes here.
+   Use named classes for button variants, dark-section overrides,
+   gradient backgrounds, etc. Keep OSUI utilities for layout/spacing. */