---
layout : 'default'
css    : 'guide'

title  : 'Spec Files'
type   : 'UI Specification'
---

<%- @partial('header') %>

<div class="main container">

  <h2>Introduction</h2>

  <p>Semantic defines an exchange format for user interface. Writing your interface components to match the specifications allows others to easily use your interface components in their project.</p>


  <h3>Writing a Spec File</h3>

  <p>Before authoring an element you should begin by writing a spec file for your element. A specification file defines the structure and names used inside your element. For more information on naming convention visit our css and html guides.</p>
  <p>A spec file also allows you to provide metadata to generate code for your element, this can be used to generate visual documentation of your element.</p>

  <h3>Common Specification</h3>

  <p>A spec file is a specially formatted json file.</p>
  <div class="code" type="javascript">
    {
      // your element name should be a single word and match to the classname of your element
      "Name": "Button",

      // you may include metadata
      "Author": "Jack Lukic",
      "Website": "http://www.semantic-ui.com"
      "Version": "2.0",

      // All elements must specify whether it is an element, collection, module, or behavior
      "Type": "Element",

      // Types are exclusive forms of your element. For example a button cannot be an icon button and a text button. The definitions of the html structure of each element is written using emmet syntax. These are used to generate html structures for your elements. For more information visit: http://docs.emmet.io/abbreviations/syntax/
      "Types": {
        "Standard"     : ".ui.button",
        "Icon"         : ".ui.icon.button > i.icon",
      }

      // States are ways which elements show an innate change in its quality.
      "States": {
        "Active"   : "active",
        "Loading"  : "loading",
        "Disabled" : "disabled"
      },


      // Variations are individual classnames which your element may receive to alter its look. Variations should, for the most part, be able to be used together to create more complex styles of an element.
      "Variations": {
        // If a set of variations are options of a single type (for example sizing may contain, small, medium, etc) then this can be defined as an array.
        "Size": [
          "mini",
          "tiny",
          "small",
          "medium",
          "large",
          "huge",
          "massive"
        ],
        "Color": [
          "black",
          "green",
          "red",
          "blue",
          "green",
          "red",
          "teal"
        ],
        "Ordinality": [
          "secondary",
          "tertiary"
        ],
        "Attached": [
          "attached top",
          "attached bottom",
          "attached left",
          "attached right"
        ],
        "Circular" : "circular",
        "Fluid"    : "fluid"
      },

      // You may define a list of dummy text and selectors which can be filled with them. This is used by generators to export a style guide of your interface element. If you specify an array, each item will be used in order to fill the content of each match.
      "Text": {
        ".ui.button": ["Button", "Click Me", "Lorem Ipsum"]
      },

      // Your module may optionally include a text definition of its variations to help clarify their purpose. This may include the definition of types or variations
      "Definition": {
        "Standard"   : "A simple button",
        "Icon"       : "A button icon is formatted to contain only an icon",
        "Size"       : "A button can vary in size",
        "Color"      : "A button can have different colors",
        "Ordinality" : "A button can blend into a page",
        "Attached"   : "A button can attach to other content",
        "Circular"   : "A button can be circular",
        "Fluid"      : "A button can be fluid"
      }
    }
  </div>

  <h3>UI Elements</h3>

  <p>A UI element is a basic building block of a website. It may have a singular or group (plural) definition</p>

  <div class="code" type="javascript">
    {
      // in addition to the parameters above an element may contain a definition for its singular and plural type
      "Types": {
        // these types can only exist for class="ui button"
        "Singular": {
          "Standard"     : ".ui.button",
          "Icon"         : ".ui.icon.button > i.add.icon",
          "Labeled Icon" : ".ui.labeled.icon.button > i.add.icon"
        },
        // these types can exist only for class="ui button"
        "Group": {
          "Standard"    : ".ui.buttons > .button+.button+.button",
          "Icon"        : ".ui.buttons > ( (.button > i.icon.user) + (.button > i.icon.heart) + (.button > i.icon.lab))",
          "Conditional" : ".ui.buttons > .button+.or+.button",
          "Vertical"    : ".vertical.ui.buttons > .button+.button+.button"
        }
      }
    }
  </div>


</div>