# README Standards MDC Web component documentation serves two purposes: * Populate the [Catalog Site](https://material.io/components/web/catalog/) * Highlight how to use our APIs, for our external developers. ## README Template Please follow the [README template](readme_template.md) *exactly*. This format is read/understood by the [Catalog Site](https://material.io/components/web/catalog/) ## Basic Usage The 'Basic Usage' section documents the bare minimum to get the most basic version of this component up and running, including: * HTML structure * Style import * JavaScript import and instantiation, if applicable ~~~ ### HTML Structure ```html ``` ~~~ In the 'Styles' subsection, include any imports and mixin invocations necessary to make the component look as desired. ~~~ ### Styles ```scss @import "@material/button/mdc-button"; // Include necessary mixin invocations here ``` ~~~ In the 'JavaScript Instantiation' subsection, include a note about importing a JavaScript component with a link to our importing documentation. ~~~ ### JavaScript Instantiation ```js import {MDCButton} from '@material/button'; const button = new MDCButton(document.querySelector('.mdc-button')); ``` > See [Importing the JS component](../../docs/importing-js.md) for more information on how to import JavaScript. ~~~ ## Variants If the component has variants, add a subsection for each variant, under the 'Variants' section. Include a short description of the variant along with the necessary HTML structure. ~~~ ### Foo Button Short description of Foo Button. ```html ``` ~~~ ## Style Customization CSS classes are documented in [tabular format](#tabular-format). ~~~ ### CSS Classes CSS Class | Description --- | --- `mdc-foo` | Indicates the foo ~~~ CSS custom properties (if applicable) are also documented in [tabular format](#tabular-format). ~~~ ### CSS Custom Properties CSS Custom Property | Description --- | --- `mdc-bar` | The bar ~~~ Sass mixins, variables, and functions are documented in [tabular format](#tabular-format) under a single subsection. Only include the tables that are applicable. You can include subsections or separate the tables into smaller tables if it makes the documentation easier to read (e.g. having two tables for Basic Mixins and Advanced Mixins). ~~~ ### Sass Mixins, Variables, and Functions Mixin | Description --- | --- `mdc-foo($value)` | Sets the foo Function | Description --- | --- `mdc-bar($value)` | Sets the bar Variable | Description --- | --- `mdc-bar` | Value of baz ~~~ You may add additional subsections at your discretion, such as Additional Information, Tips & Tricks, Util API, Caveats, etc. ~~~ ### Additional Information #### Some special case Explanation of this special case. ~~~ ## `MDCComponent` Properties and Methods This section documents the properties and methods of the vanilla JS component class, e.g. `MDCButton`. They are documented in [tabular format](#tabular-format). ~~~ Property | Value Type | Description --- | --- | --- `foo` | String | Proxies to the foundation's `getFoo`/`setFoo` methods ~~~ ~~~ Method Signature | Description --- | --- `doFoo() => void` | Does the foo ~~~ ## Usage within Web Frameworks This section documents usage of the Adapter and the Foundation. Methods are documented in [tabular format](#tabular-format). ~~~ ### `MDCTextFieldAdapter` Method Signature | Description --- | --- `getFoo() => string` | Returns the foo ~~~ ~~~ ### `MDCTextFieldFoundation` Method Signature | Description --- | --- `getBar() => string` | Returns the bar ~~~ ## Tabular format The tabular format is meant to * Keep documentation short * Facilitate showing changes in APIs, through row diffs All tables should follow this pattern: ``` | Description --- | --- | ``` * `COLUMN_NAME` should be title case, e.g. Method Signature * `INLINE_CODE` should always be formatted as inline code, e.g. `foo` * `ONE_LINE_DESCRIPTION` should not be more than one line long If you need more than one line to describe code, create a row with a summary description. Then create a note below the table with the longer description, formatted in this way: ~~~ > _NOTE_: This is the long description. ~~~ Keep descriptions brief, to make the table as easy to read as possible.