form-jekyll

form-jekyll is a Jekyll theme that lets you easily build a prototype of an SF.GOV form in a YAML file. Right now, it lets you add:

• Multiple field types
• Custom error messages
• Custom input widths, tied to the maxlength attribute
• Conditionals for radio buttons, checkboxes, and text fields
• "Less than" or "greater than" conditionals for number fields
• Markdown-formatted content

Since YAML is easy to read, non-technical colleagues can easily give feedback on form design and content inside a GitHub pull request. And because GitHub Pages uses Jekyll, you can easily deploy a form to a webpage and send the link to external stakeholders.

• Designers can prototype, comment, and iterate on forms as easily as they might a Google Doc.

• Designers can easily give external stakeholders a realistic preview of how a form will work.

https://form-jekyll.netlify.com/

First, set up Jekyll, and run bundle install to install the Gemfile.

Then, set up your development server with bundle exec jekyll serve --watch.

• Create a new Jekyll project

• Add form-jekyll to the Gemfile

• Add a YAML file named after your form to the _data directory. (If the directory doesn't exist, create it.)

• Add an HTML file to the root directory with the front matter:

  ---
  title: [Title of form]
  form: [name of YAML file, without the extension]
  ---
  

• Now it's time to start writing your form! Here's an example of what your YAML file might look like.

  - title: Page Title
    fields:
    - label: Name
  
    - label: Phone number
      type: phone
      error: You need to enter a valid phone number.
  
    - label: Do you have an email address?
      type: radio
      options:
      - label: Yes
        shows: email-field
  
      - label: No
        hides: email-field
  
    - group: email-field
      fields:
      - label: Enter your email address here
        type: email
  
    - label: How did you hear about us?
      optional: true
  

  (Scroll down for a full list of field properties.)

• _includes/fields: partials for all field types. (If you want to add a field type, place it here.)
• _includes/elements: partials for standard HTML elements (like labels and help text)
• _includes/sfgov: partials for SF.gov-specific patterns
• _includes/pages: Standard pages for the form (like preview and confirmation pages)

Visiting your development server (usually localhost:4000) will show the "Choose a prototype" page. Click on one of the forms to preview it.

Since you're building a prototype, you're also able to preview your forms at different levels of abstraction: you can see all pages on the same screen, view annotations from the form's creator, or toggle all conditionally hidden fields.

To toggle these settings, press Command + Option + . or Control + Option + . when viewing a prototype.

Clicking the admin panel will also toggle Hypothes.is, a plug-in that lets external stakeholders annotate webpages with copyedits or general feedback. (You need to register with Hypothesis in order to leave comments.)