Form Upgrade Skill

The key insight: Without formStyling on the Questionnaire, a form renders inside modern-form-container which adds gradient bars, radial overlays, and decorative shadows. The formStyling extension triggers formStylingToCSS() which generates a "document mode reset" that strips all of that. This is why formStyling is mandatory, not optional.

Field Layout Inside Inline Groups

When fields share an inlineGroup, FormRenderer wraps them in a flex row:

<div class="form-inline-group">           ← display:flex, gap:8px, flex-wrap:wrap
  <div class="form-inline-field" style="width:calc(49% - 4px)">  ← field 1
    [TextFieldRenderer or NumberDateFieldRenderer]
  </div>
  <div class="form-inline-field" style="width:calc(49% - 4px)">  ← field 2
    [TextFieldRenderer or NumberDateFieldRenderer]
  </div>
</div>

The renderer automatically applies calc(${width} - 4px) for percentage widths to account for the 8px flex gap. So widths like 49% become calc(49% - 4px).

Migrating a Hardcoded Form ≠ Copying It

When the user asks to migrate/recreate a hardcoded form using the Form Builder, your job is to:

1. Read the original template to understand the FIELDS (types, labels, bindings)
2. REDESIGN the layout following this skill's rules (widths, headers, spacing)
3. Create the seed script with the improved layout

Never copy field definitions verbatim from form-templates/*.ts into the seed script. Always run through the Migration Checklist (after Step 2). The goal is a BETTER form, not an identical copy.

How Labels Render in Inline Groups

This is where most visual bugs come from. When showLabel: true is set on a field inside an inline group, the renderer creates an inline label layout:

┌─── field container (e.g., width: 49%) ───────────┐
│ [Label text (nowrap, flex-shrink:0)] [Input (flex:1)] │
└──────────────────────────────────────────────────┘

The label is white-space: nowrap and flex-shrink: 0, so it takes its full text width. The input gets whatever space is left. Georgian labels are typically 100-250px wide. If the container is too narrow, the input becomes a tiny sliver.

This is why you must size fields based on their label length, not just field count.

Step 1: Identify the Form

Ask the user which form to upgrade. Find it by:

• Searching packages/app/src/emr/data/form-templates/ for the template file
• Checking packages/app/src/emr/scripts/ for existing seed scripts
• Looking at localTemplateRegistry.ts for the form ID

Read the full template to understand every field.

Step 2: Analyze and Fix Layout Issues (MANDATORY)

This step is NOT optional. Even if the original form "works," you MUST check every field against the rules below and fix issues. When migrating a hardcoded form, treat the original layout as a rough draft — your job is to produce a professional medical document, not a pixel-perfect copy.

Common Problems and Fixes

Migration Checklist (MANDATORY before writing the seed script)

When migrating a hardcoded form, verify EVERY item below. Do NOT proceed to Step 3 until all items pass.

• Form title: Centered display field at the top with form number + Georgian name (e.g., "ფორმა № IV-100/ა — ცნობა ჯანმრთელობის მდგომარეობის შესახებ")
• Section headers: Every major section uses the styled sectionHeader pattern — centered, bold, borderBottom: 2px solid var(--emr-primary), not plain text
• Percentage widths: All inline groups use percentage widths (49%, 32%, etc.) — never auto, flex:1, or raw pixel widths for containers
• Georgian label widths: Every field's width is checked against the label width table (short=32%, medium=40%, long=49%, very long=58%+)
• Textareas standalone: All textareas are full-width, outside inline groups, with explicit marginBottom: '16px'
• Date fields: Use 200px width (not 120px or 280px)
• formStyling: Uses the document mode reset template (no border, no boxShadow on container)
• No verbatim copies: Field definitions are redesigned, not copied from form-templates/*.ts
• Inline labels: Numbered section labels in inline groups use whiteSpace: 'nowrap' and display: 'inline-block'

Step 3: Create/Rewrite the Seed Script

Create a seed script at packages/app/src/emr/scripts/seed-{form-name}.ts.

Boilerplate

import type { MedplumClient } from '@medplum/core';
import type { Extension } from '@medplum/fhirtypes';
import { toQuestionnaire } from '../services/fhirHelpers';
import type { FormTemplate, FieldConfig, FieldStyling, PatientBinding } from '../types/form-builder';
import { QUESTIONNAIRE_EXTENSIONS } from '../constants/fhir-systems';

export const FORM_ID = 'form-xxx-name';
const FORM_URL = 'http://medimind.ge/fhir/Questionnaire/form-xxx-name';

// Helper: create a field with sensible defaults
function field(config: {
  id: string;
  type: FieldConfig['type'];
  label: string;
  text?: string;
  readOnly?: boolean;
  required?: boolean;
  patientBinding?: PatientBinding;
  inlineGroup?: string;
  width?: string;
  showLabel?: boolean;
  styling?: Partial<FieldStyling>;
  options?: FieldConfig['options'];
  order?: number;
}): FieldConfig {
  const isDisplay = config.type === 'display';
  const inGroup = !!config.inlineGroup;
  const styling: FieldStyling = {
    ...(config.width ? { width: config.width } : {}),
    ...(!isDisplay ? { inputStyle: 'underline' as const } : {}),
    // Display fields: prevent CSS truncation of long Georgian text
    ...(isDisplay ? { whiteSpace: 'normal', lineHeight: '1.6' } : {}),
    ...(inGroup && !isDisplay ? { showLabel: config.showLabel !== false } : {}),
    ...config.styling,
  };
  return {
    id: `field-${config.id}`,
    linkId: config.id,
    type: config.type,
    label: config.label,
    text: config.text,
    readOnly: config.readOnly,
    required: config.required,
    patientBinding: config.patientBinding,
    inlineGroup: config.inlineGroup,
    options: config.options,
    order: config.order,
    ...(Object.keys(styling).length > 0 ? { styling } : {}),
  };
}

function binding(key: PatientBinding['bindingKey']): PatientBinding {
  return { enabled: true, bindingKey: key };
}

Width Rules — Accounting for Inline Labels

The most common layout bug is fields that are too narrow for their Georgian labels. Here's how to size fields correctly:

Rule: Width must accommodate BOTH the label text AND the input.

When showLabel: true (the default in inline groups), the field renders as: [Label (nowrap)] [Input (flex:1)] inside the width you specify.

Width formulas for inline groups:

2 fields, both with labels:  49% + 49% = 98%  ✓
2 fields, one wide label:    58% + 40% = 98%  ✓
3 fields, short labels:      32% + 32% + 32% = 96%  ✓
3 fields, one long label:    46% + 26% + 26% = 98%  ✓
1 wide + 2 narrow:           48% + 24% + 24% = 96%  ✓

When labels are too long for the row:

If you need 3 fields but all have long labels, don't force them onto one row. Either:

• Split into 2 rows (2 fields + 1 field)
• Use showLabel: false and add separate display-type label fields above

Date fields need extra width: Date pickers have a calendar icon and wider input. Always allocate at least 49% for a date field with a label in an inline group.

Section Headers

Section headers use type: 'display'. The formStyling document mode reset makes them render as clean centered text (no gradient boxes):

field({
  id: 'section-name',
  type: 'display',
  label: 'სექციის სახელი',
  styling: {
    textAlign: 'center',
    fontWeight: 'bold',
    fontSize: 'var(--emr-font-md)',
    marginTop: '16px',
    marginBottom: '8px',
  },
})

Field Patterns

Patient-bound fields — auto-populate from patient data, always read-only:

field({
  id: 'full-name',
  type: 'text',
  label: 'სახელი, გვარი',
  readOnly: true,
  patientBinding: binding('fullName'),
  inlineGroup: 'demo-row',
  width: '48%',
})

Textareas — always full-width, standalone (NEVER in inline groups):

field({
  id: 'diagnosis',
  type: 'textarea',
  label: 'დიაგნოზი',
  styling: { height: '44px', width: '100%', marginBottom: '8px' },
})

Signature fields — always full-width, standalone (NEVER in inline groups):

field({
  id: 'doctor-signature',
  type: 'signature',
  label: 'ხელმოწერა',
  styling: { width: '100%' },
})

Integer fields in document forms — use 'text' type to avoid spinner arrows:

field({
  id: 'bed-days',
  type: 'text',  // NOT 'integer' — avoids ugly spinner controls
  label: 'საწოლ-დღე',
  inlineGroup: 'row-1',
  width: '49%',
})

formStyling — MANDATORY

Every form template MUST include formStyling. This triggers the document mode reset via formStylingToCSS(). Without it, the form renders with gradient decorations.

const formStyling: FormTemplate['formStyling'] = {
  container: {
    maxWidth: '900px',
    padding: '32px 40px',
    backgroundColor: 'var(--emr-bg-card)',
    boxShadow: 'none',
  },
  title: {
    textAlign: 'center',
    fontSize: 'var(--emr-font-xl)',
    fontWeight: '700',
    color: 'var(--emr-primary)',
    marginBottom: '8px',
  },
  label: {
    fontSize: 'var(--emr-font-sm)',
    fontWeight: '500',
    color: 'var(--emr-text-secondary)',
    marginBottom: '2px',
  },
  sectionHeader: {
    fontSize: 'var(--emr-font-md)',
    fontWeight: '700',
    color: 'var(--emr-primary)',
    padding: '8px 0',
    borderBottom: '2px solid var(--emr-primary)',
    marginBottom: '12px',
    textAlign: 'center',
  },
};

Complete Template Assembly

export const formTemplate: FormTemplate = {
  id: FORM_ID,
  title: 'ფორმის სახელი',
  description: 'ფორმის აღწერა',
  status: 'active',
  version: '1.0',
  fields,
  formStyling,
  multiRecord: false,
  signatureRequirement: 'dual',
  categories: ['General'],
  encounterPhases: ['admission'],
  encounterType: 'inpatient',
};

Seed Function — Idempotent

export async function seedForm(medplum: MedplumClient): Promise<string> {
  const questionnaire = toQuestionnaire(formTemplate);
  questionnaire.url = FORM_URL;

  // Add golden form metadata extensions
  const goldenExtensions: Extension[] = [
    { url: QUESTIONNAIRE_EXTENSIONS.FORM_MULTI_RECORD, valueBoolean: false },
    { url: QUESTIONNAIRE_EXTENSIONS.FORM_SIGNATURE_REQUIREMENT, valueString: 'dual' },
    { url: QUESTIONNAIRE_EXTENSIONS.FORM_ENCOUNTER_TYPE, valueString: 'inpatient' },
  ];

  for (const cat of formTemplate.categories ?? []) {
    goldenExtensions.push({ url: QUESTIONNAIRE_EXTENSIONS.FORM_CATEGORY, valueString: cat });
  }
  for (const phase of formTemplate.encounterPhases ?? []) {
    goldenExtensions.push({ url: QUESTIONNAIRE_EXTENSIONS.FORM_ENCOUNTER_PHASE, valueString: phase });
  }

  questionnaire.extension = [...(questionnaire.extension || []), ...goldenExtensions];

  // Upsert: search by URL, update if exists, create if not
  const existing = await medplum.searchResources('Questionnaire', { url: FORM_URL });
  if (existing.length > 0) {
    questionnaire.id = existing[0].id;
    const result = await medplum.updateResource(questionnaire);
    return result.id!;
  }
  const result = await medplum.createResource(questionnaire);
  return result.id!;
}

Step 4: Register the Form (if new)

If the form needs to appear in the patient card sidebar:

1. activityTabConfig.ts — Add form ID to the appropriate tab's formIds array
2. inpatientFormCategories.ts — Add sidebar entry under the right category group
3. SimpleFormSidebar.tsx — Add same entry (it has its own copy)
4. formComponentRegistry.tsx — Add lazy import + registration
5. Create content wrapper — Form{Name}Content.tsx using SharedFormRendererContent

DO NOT add entries to FORM_CLASS_MAP or FORM_CSS_LOADERS in FormRenderer.tsx. The formStyling extension handles styling through runtime CSS injection.

Step 5: Verify with Playwright

After creating the form, verify the rendering:

# Start server if needed
cd packages/app && npx vite --port 3000

# Navigate and screenshot
npx tsx scripts/playwright/cmd.ts navigate "<patient-card-url>"
npx tsx scripts/playwright/cmd.ts wait 2000
npx tsx scripts/playwright/cmd.ts screenshot "form-check"

# Check for wrapping issues (inline groups where fields wrapped to next line)
npx tsx scripts/playwright/cmd.ts evaluate "
  const groups = document.querySelectorAll('[data-inline-group]');
  const issues = [];
  for (const g of groups) {
    const children = Array.from(g.children);
    if (children.length < 2) continue;
    const last = children[children.length - 1];
    const first = children[0];
    if (last.getBoundingClientRect().top > first.getBoundingClientRect().top)
      issues.push(g.getAttribute('data-inline-group'));
  }
  JSON.stringify({ total: groups.length, wrapping: issues });
"

Zero wrapping groups = success. If any group wraps, reduce field widths in that row.

DO NOT Rules

1. DO NOT put textareas in inline groups — they always render full-width
2. DO NOT put signature/attachment fields in inline groups — they're too large
3. DO NOT put checkbox-group or radio fields in inline groups
4. DO NOT use width less than 32% for any field with a Georgian label
5. DO NOT put datetime fields in inline groups with other labeled fields — they're too wide (label + calendar + clear button = ~430px). Put datetime fields standalone or only pair with SHORT-label fields
6. DO NOT use width less than 49% for date fields with labels in inline groups
7. DO NOT use 'integer' type in document forms — use 'text' to avoid spinners
8. DO NOT use height on textarea fields — use CSS min-height or omit it. Fixed height on the wrapper prevents autosize expansion, causing textareas to overlap elements below
9. DO NOT omit formStyling — it's what makes the form look like a document
10. DO NOT add to FORM_CLASS_MAP or FORM_CSS_LOADERS — use formStyling instead
11. DO NOT hardcode colors — use var(--emr-xxx) CSS variables
12. DO NOT use widths that sum to exactly 100% — leave 2-4% slack for the gap
13. DO NOT use hardcoded pixel widths over 200px for date pickers — the EMRDatePicker content (icon + date text + clear button) only needs ~200px. Using 280px or larger wastes 80px of empty space
14. DO NOT use maw (max-width) under 300px for Select fields — Georgian medical text (e.g., "გადაუდებელი განყოფილება (ER)") needs ~250px. Default maw should be 300px when no explicit fieldStyling.width is set
15. DO NOT copy field definitions 1:1 from hardcoded templates during migration — always redesign the layout by running through the Migration Checklist above. The goal is a BETTER form, not an identical copy
16. DO NOT put date fields with Georgian labels in ANY inline group — the label (flex-shrink:0, ~200px) steals space from the date picker, causing it to collapse to a tiny icon. ALWAYS make date fields with labels standalone at width: '100%'. The only exception: labelless dates (empty label, showLabel:false) paired with a separate display label in an inline group
17. DO NOT use different label widths for vertically-stacked inline groups that should align — when multiple rows of "label + input" appear under the same section (like date sub-rows 8a-8d), give ALL labels the same fixed width so inputs align vertically. Use a shared style constant like dateRowLabel: { width: '300px', flexShrink: '0' }
18. DO NOT omit whiteSpace: 'normal' on display fields with long text (legal clauses, paragraph descriptions). FormRenderer CSS applies white-space: nowrap; overflow: hidden; text-overflow: ellipsis to inline field text, which TRUNCATES long Georgian text to just the first few characters. Always add whiteSpace: 'normal' and lineHeight: '1.6' to display fields that contain paragraph-length text

Troubleshooting

Available Patient Binding Keys

fullName, firstName, lastName, dob, age, personalId, gender, phone, email, address, workplace, bloodGroup, rhFactor, allergies, citizenship, department, transportationType, admissionDate, dischargeDate, registrationNumber, treatingPhysician, practitionerName, clinicName

CSS Variables (never hardcode colors)

• Primary: var(--emr-primary) (#1a365d), var(--emr-secondary) (#2b6cb0)
• Surface: var(--emr-bg-card), var(--emr-bg-input), var(--emr-bg-page)
• Text: var(--emr-text-primary), var(--emr-text-secondary)
• Border: var(--emr-border-default), var(--emr-border-color)
• Font sizes: var(--emr-font-xs) through var(--emr-font-3xl)

Reference: Working Seed Script

See packages/app/src/emr/scripts/seed-form-300a-v2.ts for a complete, tested example that demonstrates all patterns: inline groups with labels, section headers, textareas, date fields, signatures, patient bindings, and formStyling.