list-formatting

Files (4)

• SKILL.md
• advanced.md · references/
• patterns.md · references/
• visual.md · references/

SKILL.md (first lines)

<!--
  SharePoint List Formatting Skill
  Created by Zach Rosenfield (github.com/zrosenfield)

  Built with knowledge from:
  - Microsoft Learn: SharePoint declarative customization docs
    https://learn.microsoft.com/en-us/sharepoint/dev/declarative-customization/column-formatting
    https://learn.microsoft.com/en-us/sharepoint/dev/declarative-customization/view-list-formatting
    https://learn.microsoft.com/en-us/sharepoint/dev/declarative-customization/formatting-syntax-reference
  - PnP List Formatting Samples (MIT License)
    https://pnp.github.io/List-Formatting/
    https://github.com/pnp/List-Formatting

  Sharing is Caring!
-->

# SharePoint List Formatting Skill

## Step 1: Load Additional References (if needed)

Scan the user's request and read any reference files that apply before responding:

| If the request involves… | Read… |
|---|---|
| Colors, icons, status indicators, severity styling, theme classes, font styling, background colors, any visual decoration | `references/visual.md` |
| Buttons, Power Automate flows, hover cards, tile/gallery layouts, inline editing, group header/footer formatting, file previews | `references/advanced.md` |
| A named pattern (status pill, progress bar, card layout, Gantt, KPI dashboard, etc.), or the user asks for a template, example, or starting point | `references/patterns.md` |

For open-ended "make it pretty" requests, read all three. When in doubt, read the file.

---

## Step 2: Think Big Before You Build

When the user asks to "make it pretty", "style my view", or gives any open-ended visual request — **do not default to incremental tweaks**. Treat it as an invitation to fundamentally reimagine the experience.

Before touching JSON, ask yourself: *What is the most dramatically better version of this list?*

**Default to transformation, not decoration:**
- Prefer a `rowFormatter` card layout over adding row highlight colors
- Prefer a tile/gallery view over a plain list with styled columns
- Prefer rich column formatters (status pills, avatar+name, progress bars, due date urgency) over plain text with background colors
- Propose a **complete visual system** — not isolated column tweaks

**Name your vision first.** Before producing JSON, describe what you're building in one sentence. This lets the user redirect before you build the wrong thing.

**Propose the boldest option, then offer alternatives.** Lead with the most dramatic transformation. Mention a simpler fallback if they want something lighter.

---

## Formatting Scopes

Four distinct scopes — pick the right one, or combine them:

- **Column formatting** — Styles a single column's cells. Applied via: Column Settings > Format this column > Advanced mode. `@currentField` is the column's value.
- **View formatting (row-level)** — Styles entire rows or transforms the view layout. Applied via: View dropdown > Format current view > Advanced mode. Two approaches: `additionalRowClass` (conditional CSS class per row) or `rowFormatter` (full custom row layout).
- **Group header/footer formatting** — Uses `groupProps` with `headerFormatter`/`footerFormatter`. Access group data with `@group` token.
- **Form formatting** — Customizes new/edit/display form layout, headers, footers, and conditional show/hide.

## JSON Schemas

Always include the correct `$schema`:

| Formatter type | Schema |
|---|---|
| Column formatting | `https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json` |
| View with `rowFormatter` | `https://developer.microsoft.com/json-schemas/sp/v2/row-formatting.schema.json` |
| View with `additionalRowClass` only | `https://developer.microsoft.com/json-schemas/sp/view-formatting.schema.json` |
| Tile/gallery view | `https://developer.microsoft.com/json-schemas/sp/v2/tile-formatting.schema.json` |

## Element Types (elmType)

| elmType | Description |
|---------|-------------|
| `div` | Block container. Most common wrapper. |
| `span` | Inline container. Good for text alongside other elements. |
| `a` | Hyperlink. Requires `href` attribute. |
| `img` | Image. Requires `src`. Subject to domain restrictions. |
| `svg` / `path` | Vector graphics. `path` requires `d` attribute. |
| `button` | Clickable button. Requires `customRowAction`. |
| `filepreview` | Document library thumbnail. Set `src` to `@thumbnail.medium`. |

## Key Properties

- **`txtContent`** — Text content of the element (string or expression). If set, `children` are ignored.
- **`style`** — CSS property/value pairs. Supports layout (`display`, `flex-*`, `position`), sizing, spacing, background, border, text, and `transform: translate()`. Use flexbox; `float` is deprecated.
- **`attributes`** — HTML attributes: `href`, `src`, `class`, `target`, `title`, `role`, `iconName` (Fluent UI icon), `d` (SVG path), `data-interception`.
- **`children`** — Array of child element objects. Ignored if `txtContent` is set.
- **`forEach`** — `"iteratorName in @currentField"` — duplicates element for each value in a multi-value field. Cannot be on the root element.
- **`debugMode`** — Set `true` to log errors to browser console.

## Expressions

Prefer Excel-style (`=` prefix). Examples:
```
=if(@currentField == 'Done', 'sp-field-severity--good', '')
=if([$DueDate] <= @now, '#a4262c', 'inherit')
='mailto:' + @currentField.email
=toString(floor(@currentField * 100)) + '%'
```

**Operators**: `+`, `-`, `*`, `/`, `%`, `==`, `!=`, `<`, `>`, `<=`, `>=`, `&&`, `||`, ternary `?`

**String**: `toString()`, `toLowerCase`, `toUpperCase`, `indexOf`, `startsWith`, `endsWith`, `substring`, `replace`, `replaceAll`, `padStart`, `padEnd`, `split`, `join`, `length` (array count only — not string length)

**Number**: `Number()`, `abs`, `floor`, `ceiling`, `pow`, `cos`, `sin`, `toLocaleString()`

**Date**: `Date()`, `getDate`, `getMonth` (0-based), `getYear`, `addDays`, `addMinutes`, `toLocaleDateString()`, `toLocaleString()`

**Array**: `appendTo`, `removeFrom`, `indexOf`, `join`, `length`

**Images**: `getUserImage(email, size)` — sizes: `'small'`/`'s'`, `'medium'`/`'m'`, `'large'`/`'l'`

## Special Tokens

| Token | Description |
|-------|-------------|
| `@currentField` | Column value. In `rowFormatter`, always resolves to Title — use `[$FieldName]` instead. |
| `@currentField.title` / `.email` / `.id` / `.picture` / `.department` / `.jobTitle` | Person field sub-properties |

From zrosenfield/sharepoint-ai-skills, MIT.

More from zrosenfield/sharepoint-ai-skills