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.