List Styling

List Styling Engine

Transform SharePoint lists and document libraries into fully art-directed views. This is not a color palette swap — it's a complete visual redesign using every formatting capability SharePoint provides.

The bar: "I can't believe that's SharePoint."

Formatting Capabilities — Use ALL of These

SharePoint provides four levels of formatting. A properly styled view uses MULTIPLE levels together. Do not stop at column formatting.

Level 1: Column Formatting

Per-column rendering. Controls how individual cell values display.

• Status badges, progress bars, date compositions
• Applied via: Column header → Column settings → Format this column → Advanced mode

Level 2: View Formatting (additionalRowClass)

Adds CSS classes to existing rows. Lightweight — doesn't change layout.

• Alternating row colors, conditional row highlighting (overdue tinting)
• Applied via: View dropdown → Format current view → Advanced mode

Level 3: Row Template (rowFormatter)

REPLACES the entire row layout. This is the power move. Instead of SharePoint's default column grid, you define the complete HTML structure of each row.

• Full card layouts with sidebars, composed metadata, multi-section rows
• Can combine multiple columns into a single visual composition
• Applied via: View dropdown → Format current view → Advanced mode (uses rowFormatter key instead of additionalRowClass)

Level 4: Tile Formatting

Gallery/card view layouts. Each item renders as a card instead of a row.

• Standalone card designs with headers, bodies, footers, progress indicators
• Applied via: Gallery view → Format current view → Advanced mode

Rule: Every style MUST use at least Level 1 + Level 3. Level 3 (rowFormatter) is what creates the "I can't believe it" impact. Column formatting alone is a 3/10.

The Style Application Workflow

Step 1: Read the list schema — required before generating any JSON

Know the columns, their internal names, types, and Choice values. Get this from SHAREPOINT.md if available, or ask the user. Do not generate any JSON until you have the actual column names and Choice values.

Step 2: Read the style token file

Load the matching style-{name}/style-{name}/SKILL.md. It contains design tokens and a rowFormatter reference template. The column names in that template ([$Status], [$Progress], [$Deadline]) are example placeholders that almost certainly do not match the user's list.

Step 3: Map the user's columns to the template

The style file's rowFormatter uses reference column names: [$Title], [$FileLeafRef], [$Status], [$Progress], [$Deadline]. These are examples — the user's list will likely have different column names.

Before applying the rowFormatter, you MUST adapt it:

Column-discovery checklist

Run this checklist against the schema you read in Step 1 before you start the find-and-replace. If you skip it, the generated JSON will reference columns that don't exist and the view will render blank cells.

• List every column the user's list actually has, with its internal name (not display name). Spaces in display names become _x0020_ in internal names — the rowFormatter uses internal names.
• Confirm the four role columns are present and capture each one:
  • Name/Title role → internal name = ______
  • Status role (Choice) → internal name = ______, choices = ______
  • Progress role (Number 0–100) → internal name = ______
  • Deadline role (DateTime) → internal name = ______
• Capture the exact Choice values for the Status column — case-sensitive. "In Progress" ≠ "in progress" ≠ "InProgress".
• Note the Number column scale. SharePoint stores 0.72 for a 72% slider but 72 for a free-entry number column. The rowFormatter must treat the value accordingly — do not assume.
• Check the Date column format. Date-only vs Date-and-time changes which expression to use for overdue comparisons against @now.
• List any "extra" columns the user wants surfaced (Owner, Priority, Category, etc.) and decide their slot per Step 3 rule 4 below.
• List any "missing" template columns (e.g. the user has no Deadline) and mark the corresponding rowFormatter section for removal per Step 3 rule 5.

If any item above cannot be filled in from the schema, stop and ask the user — do not guess column names or choice values.

1. Identify which column in the user's list serves each role:

   • Name/Title role: The item or document name (e.g., [$Title], [$FileLeafRef], [$ProjectName])
   • Status role: A Choice column with workflow states (e.g., [$Status], [$Phase], [$Stage])
   • Progress role: A Number column 0-100 (e.g., [$Progress], [$Completion], [$PercentComplete])
   • Deadline role: A DateTime column (e.g., [$Deadline], [$DueDate], [$TargetDate])

2. Find-and-replace all [$ReferenceName] values in the rowFormatter JSON with the actual internal column names.

3. Update the status_colors if() expressions to use the actual Choice values from the user's list. If they use "Active" instead of "In Review", or "Complete" instead of "Published", remap accordingly using the same color logic from the style tokens.

4. If the user's list has ADDITIONAL columns not covered by the style template (e.g., Owner, Priority, Category), decide where to surface them:

   • In the sidebar/panel area alongside existing metadata
   • In the main content area replacing the "Open Item" button
   • As additional inline elements in the metadata row

5. If the user's list is MISSING a column the template expects (e.g., no Deadline column), remove that section from the rowFormatter rather than letting it error.

The style's rowFormatter is a reference implementation. Adapt it to the user's data — do not paste it verbatim.

Step 4: Generate formatters — in this order

A. Row Template (rowFormatter) — DO THIS FIRST This is the centerpiece. The style token file defines the row layout structure. Generate the complete rowFormatter JSON that composes all columns into the styled row design.

B. Column Formatters — FOR COLUMNS NOT HANDLED BY rowFormatter If the row template covers Status, Progress, and Deadline inline, you may not need separate column formatters for those. But any column NOT included in the rowFormatter still needs its own formatter.

C. View Formatting — IF the style uses alternating rows or row highlighting Add additionalRowClass only if the style specifies it AND only if you're NOT using a rowFormatter (the two conflict — rowFormatter replaces the row entirely, so additionalRowClass has no effect when rowFormatter is active).

D. Tile Formatting — IF the user wants a gallery/card view Generate tile formatting for card-based layouts.

Step 5: Create a custom view

Tell the user to create a new view named after the style (e.g., "Neobrutalism") so the formatting doesn't affect the default "All Items" view.

Step 6: Preview and test before committing

Never apply formatting to the default view, and never tell the user to skip this step. A broken rowFormatter makes a list look empty and is a frightening experience for anyone who isn't a developer.

1. Confirm the user is on the new view created in Step 5 — not "All Items" / "All Documents".
2. Have the user paste the JSON via Format current view → Advanced mode and click Preview, not Save. The preview pane renders the row template against real data without persisting it.
3. Walk through this checklist against the preview:
   • Every row renders (no blank rows, no [$ColumnName] literals leaking through).
   • Status pills show the right color for at least one row of each Choice value.
   • Progress bars show varied widths — not all 0% and not all 100%.
   • Deadline composition renders both a future date and a past date correctly (overdue treatment fires).
   • Clickable elements open the item (customRowAction with defaultClick works).
   • Resize the browser to ~600 px wide — see Step 7 below.
4. Only after the preview checklist passes, tell the user to click Save.
5. If anything in the checklist fails, iterate on the JSON — do not ask the user to save first and fix later. SharePoint will happily save a broken formatter.

Step 7: Mobile responsiveness

A styled view that looks incredible on a 1920-px monitor and breaks on a phone is half a solution. SharePoint lists are rendered in three places that matter — desktop browser, Teams mobile, and the SharePoint mobile app — and they all hit narrow viewports.

Apply these rules to every rowFormatter you generate, regardless of style:

• No fixed pixel widths greater than 240 px on row sections. The 280-px sidebar pattern that appears in several style templates clips badly on mobile. Either drop to ≤ 240 px or convert the layout to use flex with flex-basis and flex-grow so the section can shrink.
• Wrap, don't overflow. Use flex-wrap: wrap on the outer row container so the sidebar drops below the main content on narrow viewports instead of being cut off. Set min-width: 0 on text children so long titles ellipsis-truncate rather than push their parent wider.
• Hide secondary metadata under ~480 px, don't shrink it to unreadable. SharePoint supports "@window.innerWidth < 480 ? 'none' : 'flex'" style expressions — use them on tertiary chips (Owner, Category, sublabels) so the row stays scannable on a phone.
• Hero number sizing. Progress percentages and status pills that look right at 32 px on desktop are oversized on mobile. Use a step-down expression: "@window.innerWidth < 480 ? '20px' : '32px'".
• Touch targets. Anything customRowAction-clickable must be at least 44 × 44 px on mobile. Don't ship pill-clicks that only work on a mouse.
• Test the preview at ~375 px (iPhone), ~600 px (tablet portrait), and ≥ 1024 px (desktop) before saving — SharePoint's preview pane respects window resizing.

If a style token file is missing responsive breakpoints, fill them in using the rules above and report this back to the user so they know the generated formatter is more responsive than the upstream style spec.

Step 8: Apply and verify

rowFormatter Structure

This is the most powerful tool. It replaces the entire row with a custom layout.

jsonCopy code
{
  "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/view-formatting.schema.json",
  "hideSelection": false,
  "hideColumnHeaders": true,
  "rowFormatter": {
    "elmType": "div",
    "style": { ... },
    "children": [ ... ]
  }
}

Key behaviors:

• hideColumnHeaders: true — hides the default column headers since the row template defines its own layout
• Access any column value with [$InternalColumnName]
• Can compose multiple columns into a single visual element
• Supports all the same style properties as column formatters
• Can include buttons, links, icons, conditional elements

Layout patterns the style file can define:

• Card row: Full-width card per item with sidebar + main content
• Split row: Left panel (metadata) + right panel (details)
• Compact row: Single line with composed inline elements
• Summary card: Tile-style card within a list view

SharePoint JSON Formatting Reference

Supported

• elmType: div, span, a, img, svg, path, button
• All CSS properties via inline style object
• border-radius, text-transform, box-shadow, overflow, gap — all work
• Colors: hex only (#ffffff)
• Emoji in txtContent — works for icons
• customRowAction with action: "defaultClick" — makes elements clickable to open the item
• forEach — iterate over multi-value fields
• Expressions: @currentField, [$ColumnName], @now, @me, @rowIndex
• toString(), Number(), toLocaleDateString(), if(), indexOf(), substring()

NOT Supported

• backdrop-filter, gradients, rgb()/rgba()/hsl()
• Custom CSS classes in column formatters (only built-in SP classes in additionalRowClass)
• CSS variables, hover pseudo-states
• Nested if() beyond ~10 levels

Common Mistakes

• Forgetting $schema
• Display names vs internal names (spaces → _x0020_)
• Case-sensitivity on Choice values
• Number column stores 0.72 not 72
• Trailing commas (invalid JSON)
• Using additionalRowClass WITH rowFormatter (they conflict — rowFormatter wins)

What "11/10 Ambition" Looks Like

The difference between "formatted" and "I can't believe that's SharePoint":

The token file defines the row template. The engine generates it. RALPH iterates until it hits 11/10.

Application Instructions

Creating a styled view:

1. Go to the list/library
2. Click "Add view" → name it after the style (e.g., "Neobrutalism")
3. Select columns to include: the columns identified in your Step 3 mapping
4. Save the view
5. Click the view dropdown → "Format current view" → "Advanced mode"
6. Paste the rowFormatter JSON
7. For any columns NOT covered by the rowFormatter, apply individual column formatters

Important: Always create a new view. Never modify "All Items" or "All Documents" directly.