Sharepoint Safe HTML

SharePoint Safe HTML

Generate a single self-contained .html file that works reliably when hosted in SharePoint or OneDrive and opened through preview, File Viewer, Teams, or an embedded iframe.

If a narrower installed skill matches the artifact type (for example, an executive report, dossier, scorecard, or roadmap), use that skill for content structure and apply this skill's safety and accessibility contract to the final HTML.

Core Contract

Create exactly one .html file that works with:

• No network access.
• No external files by default, except explicitly approved SharePoint/OneDrive live-linked .csv or .xlsx data files.
• No external CSS, JavaScript, images, fonts, APIs, analytics, or CDNs.
• No privileged browser APIs.
• No secrets or tokens.
• No dependency on local filesystem paths.
• Semantic, accessible HTML that targets WCAG 2.2 AA unless the user explicitly asks for a different standard.

Assume SharePoint and OneDrive render the file inside a restricted sandboxed iframe. If it works locally but relies on anything outside the file, it is not SharePoint-safe.

SharePoint/OneDrive can live link up to 10 .csv or .xlsx files in the same folder as the HTML file, so the artifact updates when those files change. Treat this as the only approved external-file exception, and use it only when the user wants an auto-updating data-backed artifact.

Default Decision Rule

Prefer static, self-contained, CSS-driven HTML.

Use JavaScript only when the user explicitly needs interactivity and accepts that SharePoint/OneDrive sandbox behavior may vary. If JavaScript is used, it must be inline, dependency-free, non-networked, and progressive enhancement only. The artifact must remain useful if scripts are blocked.

Accessibility is not a final polish step. It must shape the content model, visual design, render logic, and validation pass.

Workflow

Step 1: Confirm the artifact purpose

Identify the requested output type and audience:

• Report, dashboard, deck, one-pager, comparison, timeline, scorecard, briefing, or visual page.
• Intended SharePoint/OneDrive location if provided.
• Whether interactivity is truly required.
• Source/freshness notes needed for any data shown.
• Accessibility needs implied by the artifact, including charts, tables, status messages, and keyboard interaction.

Do not ask for information the user already provided. If the request can be completed from the prompt or attached data, proceed.

Step 2: Build a static content model

Before writing HTML, decide the page sections and data to embed. Keep only the information the user intended to publish in the artifact.

For private M365, email, Teams, SharePoint, CRM, or customer data:

• Include only data required for the artifact.
• Do not hide raw source data in comments, scripts, attributes, or unused markup.
• Do not embed full source transcripts unless explicitly requested.
• Do not include tokens, cookies, connection strings, debug logs, or internal-only URLs that should not be shared.

For accessibility, define the semantic purpose of each section before rendering it:

• Page introduction.
• Summary metrics.
• Charts or visual summaries.
• Data tables.
• Notes, caveats, source, and freshness information.
• Empty, loading, and error states.

If the user wants the artifact to auto-update from source files, use live-linked .csv or .xlsx data files instead of embedding stale snapshots. Follow the live-linked data rules below before generating the final HTML.

Step 2A: Decide whether to use live-linked data files

Use live-linked data only when all conditions are true:

• The user wants the artifact to update when source data changes.
• The data source is a .csv or .xlsx file in SharePoint or OneDrive.
• Every linked .csv or .xlsx file is in the same folder as the HTML artifact.
• There are 10 or fewer linked files total.
• The linked files are appropriate for the artifact's audience and SharePoint location.
• The artifact remains safe without runtime network code written by the agent.

Rules:

• Never live link more than 10 .csv or .xlsx files.
• Keep the HTML file and every linked .csv or .xlsx file in the same SharePoint/OneDrive folder. Do not link across folders, sites, drives, tenants, or local paths.
• Do not use live-linked files for secrets, tokens, credentials, or hidden raw exports the user did not intend to publish.
• Do not mix live links with arbitrary external URLs, REST calls, Graph calls, CDNs, or local paths.
• Prefer live links for data that must stay current; prefer embedded static data for final snapshots, executive-ready exports, or sensitive data that should not expose a source workbook.
• Document every linked file in a visible source/freshness note so readers understand what drives the artifact.
• When the user asks for a live-linked report, do not embed backup rows, fallback datasets, cached snapshots, sample rows, or stale hardcoded render data. The report must be live-only.

Step 2B: Make live-linked rendering resilient

Live-linked .csv and .xlsx files can change after the HTML is created. Generate defensive render logic so updated, empty, renamed, or partially missing data does not crash the artifact.

Required reliability rules:

• Define the expected schema for every linked file before rendering: file name, sheet/table if applicable, required columns, optional columns, and how each column maps to the visual sections.
• Normalize linked data into a canonical object with safe defaults before any rendering happens.
• Initialize every collection used by the renderer as an array, even when the source file is empty or missing optional data.
• For live-linked reports, safe defaults may prevent JavaScript crashes but must not invent business data. Defaults are allowed for presentation fields such as "", 0, false, or []; they are not allowed to create backup records, fake rows, placeholder metrics, or cached content.
• Never call .map, .filter, .reduce, .forEach, or similar array methods on a value unless it has first been normalized with Array.isArray(value) ? value : [].
• Never assume nested properties exist. Read them through a normalization layer and provide explicit defaults such as "", 0, false, or [].
• If required columns are missing, render a visible configuration error panel that lists the expected columns and the columns found. Do not throw an uncaught exception or leave the page blank.
• If a linked file fails to load, cannot be parsed, is not in the same folder, exceeds the 10-file limit, or returns an unexpected shape, render a visible live-link error panel. Do not replace it with embedded backup content.
• If a linked file has zero rows, render an empty-state message for that section instead of failing.
• If individual cell values are blank or malformed, render a safe placeholder such as Not provided and keep the rest of the artifact usable.
• Keep source/freshness notes visible and include the names of linked files so users know what to fix.

Use this defensive pattern for any live-linked array before rendering:

const rows = Array.isArray(sourceRows) ? sourceRows : [];
const cards = rows.map(row => ({
  title: String(row.Title ?? row.Name ?? "Untitled"),
  status: String(row.Status ?? "Not provided"),
  value: Number.isFinite(Number(row.Value)) ? Number(row.Value) : 0
}));

Before handoff, test the generated artifact logic against these data states:

1. Normal rows with all expected columns.
2. Empty file or empty sheet.
3. Missing optional columns.
4. Missing required columns.
5. Blank cells in required columns.
6. Failed live-link load or parse failure.

The expected result for state 6 is a visible error message such as: Live data failed to load. Check that the linked CSV/XLSX files are in the same folder as this HTML file and match the expected schema. It must not show stale, sample, or hardcoded business data.

Step 3: Generate one self-contained HTML file

Use semantic HTML and inline CSS:

• Use main, section, article, header, footer, h1-h6, p, ul, ol, dl, table, figure, and figcaption where appropriate.
• Use exactly one h1 and maintain accessible heading order.
• Inline all CSS in a <style> block.
• Scope page styles under a root wrapper such as .sp-html-artifact.
• Use system fonts: "Segoe UI", Aptos, Arial, sans-serif.
• Design for iframe width and variable height.
• Use responsive layouts from about 360px wide to desktop.
• Make charts readable without hover-only interactions.
• Include source and freshness notes when presenting data.
• Ensure the artifact remains readable at 200% browser zoom.

Use this base pattern unless the requested design requires a different layout:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <meta name="color-scheme" content="light">
  <title>SharePoint-safe HTML artifact</title>
  <style>
    :root { color-scheme: light; }
    * { box-sizing: border-box; }
    body {
      margin: 0;
      font-family: "Segoe UI", Aptos, Arial, sans-serif;
      background: #f8fafc;
      color: #111827;
      line-height: 1.5;
    }
    .sp-html-artifact {
      width: 100%;
      max-width: 1440px;
      margin: 0 auto;
      padding: 24px;
    }
    .sr-only {
      position: absolute;
      width: 1px;
      height: 1px;
      padding: 0;
      margin: -1px;
      overflow: hidden;
      clip: rect(0, 0, 0, 0);
      white-space: nowrap;
      border: 0;
    }
    :focus-visible {
      outline: 3px solid #2563eb;
      outline-offset: 3px;
    }
    @media (max-width: 640px) {
      .sp-html-artifact { padding: 14px; }
    }
    @media (prefers-reduced-motion: reduce) {
      *, *::before, *::after {
        animation-duration: 0.01ms !important;
        animation-iteration-count: 1 !important;
        scroll-behavior: auto !important;
        transition-duration: 0.01ms !important;
      }
    }
  </style>
</head>
<body>
  <main class="sp-html-artifact" id="main-content">
    <header aria-labelledby="page-title">
      <h1 id="page-title">Artifact title</h1>
      <p>Lead with the most important message.</p>
    </header>
  </main>
</body>
</html>

Step 4: Use a deterministic render contract

Generate HTML through a small, explicit render pipeline so the artifact is predictable and debuggable:

1. Collect inputs: source data, user requirements, artifact title, audience, and freshness notes.
2. Normalize inputs: convert all data into canonical objects with explicit defaults.
3. Validate inputs: check required fields, expected schemas, row counts, and date/number parsing before rendering.
4. Render sections: produce each visual section from normalized data only.
5. Assemble HTML: insert rendered sections into the final document shell.
6. Validate output source: run the validation checklist before handoff.

Do not intermix raw source parsing, normalization, and HTML string construction in the same code path. Most broken artifacts come from rendering directly from unknown data shapes.

Required render safeguards:

• Every dynamic section must have an explicit empty state.
• Every known failure mode must render a visible error panel with actionable fix text.
• Errors must never be swallowed silently. If recovery is possible, show what was recovered; if recovery is not possible, show the error panel.
• Do not leave unresolved template tokens such as {{TITLE}}, {{CONTENT}}, TODO, undefined, null, [object Object], or NaN in visible output.
• Do not use placeholder business data unless the user explicitly asked for a mockup or sample. For live-linked reports, placeholder business data is always forbidden.
• Use stable section IDs and anchors so links keep working after data refreshes.
• Keep the artifact useful with JavaScript disabled unless the user explicitly accepted a JavaScript-dependent experience.

For live-linked reports, wrap the live-data initialization in a visible error boundary. The boundary may catch parsing/loading exceptions only to replace the broken section with an error panel. It must not render backup business data.

Step 5: Escape untrusted content

Escape all values from emails, chats, documents, lists, spreadsheets, M365, CRM, or user-provided data before inserting into HTML:

Never render raw untrusted HTML.

Step 6: Validate before handoff

Before handing the file to the user, verify the source, layout, and accessibility:

1. Search the source for banned patterns listed in the validation checklist.
2. Confirm all CSS is inline.
3. Confirm no external dependencies are referenced.
4. Confirm the page is readable at 360px, 768px, and desktop widths, and at 200% browser zoom.
5. Confirm there is no horizontal scrolling.
6. Confirm all meaningful images have alt text and decorative images use alt="".
7. Confirm charts and tables are readable without hover, and every chart has a text, list, or table equivalent.
8. Confirm KPI cards and status indicators expose label/value relationships and don't rely on color alone.
9. Confirm dynamic loading, refresh, success, and error states are announced through role="status"/role="alert" live regions.
10. Confirm visible focus is present and keyboard users can operate every interactive control.
11. Confirm private data is intentional and appropriate for the SharePoint location.
12. Confirm there are no unresolved placeholders, leaked JavaScript values, or accidental mock rows.
13. If possible, upload to SharePoint or OneDrive and open through preview or File Viewer.
14. If embedded on a SharePoint page, verify the actual web part/container size.

Run the full Validation Checklist and Accessibility validation checklist below before handoff.

Accessibility Implementation Contract

Target WCAG 2.2 AA unless the user explicitly asks for a different standard.

The artifact must be perceivable, operable, understandable, and robust. Build accessibility into the content model and rendering approach rather than treating it as a final checklist.

This skill's Accessibility Rules and Accessibility validation checklist below cover the rules to apply and verify on every artifact. For the full implementation patterns behind those rules — semantic page structure, live-region markup for dynamic content, accessible KPI card and table markup, accessible chart patterns, color/contrast, keyboard/focus, reduced motion, responsive/zoom behavior, image/SVG alt handling, link/button text, and plain-language guidance, each with runnable HTML/CSS examples — see references/accessibility.md. Read it before building any section that involves dynamic status, charts, tables, or KPI cards.