A major version: lines that were silently read as nothing are now read as written or said, and a few lines draw differently. Read "Reads differently" before upgrading. New: links in a text's runs, pictures that stretch from a centre slice, a clip shape on any node, banners over everything, lists that hold their place, snapping lists, lifted elements, and the device's edges in formulas. With CodelesslySDK 41.0.0.
Layout and text:
pad=[x, y](and a two-number margin) is horizontal and vertical; it was no padding at all. An inset list of another count (pad=[16,18,16]), and a list a key cannot read (viewBox=[0,0,12,12]on a Path), are said and left out; they were kept and read as nothing.top/bottomon a Column andleft/righton a Row are along it, asmiddle/centerare; they were across it. With a number on a Stack's child they are its place from that edge (right=16isx={"end":16}); they were dropped.align=on a Stack's child is its place on both axes; it was not read (the child sat at 0,0).mainAxisAlignment=centeralone on a Column centres across too when no cross alignment is written.- A text placed at a side (
Text … w=fill align=end,align=centerin a Stack) has its lines follow the side unlesstextAlignis written. A text'sstyle={…}aftercolor=/size=joins them, the later key winning; it replaced them. - A dialog's or sheet's end buttons with a written width keep it, and ones written one under another stay so; they took equal shares on a phone.
Fields:
- A multi-line field beside a box that takes a tap (a round send box) is a composer: it takes the hint and
grows from one line. A field in a framed row beside a button, or a
TextFieldin a framed row of icons (a search pill), is drawn bare, the frame taking its focus ring; it drew a second border or a white inset. - A bound border on an Input (
border={…}) is the field's own border colour or width; it went to the node's stroke.icon=noneon an Input is no icon.multiline=true(anditalic,clip,keepwritten=true) is the flag; it was refused.
Values and formulas:
if condition={a || b} then={…} else={…}reads its predicate; the condition was kept as text and the else ran. A typed state's formula (not x,and,or) is read as every other formula.- A count in braces inside a formula's quoted text (
'\d{3}',{2,}) stays text; it was read as a value. - A paint with
"colors"and number"stops"infill=/fills=is read as stop records; it drew nothing. state p:Map?=nulland capitalised type words are read;state selected:map=nullprints=null. A sheet's stop variable declared as a whole number is widened to a decimal.- A worked-out value in a field that takes one written out (
delay ms={x ? 4000 : 3000}) moves to the field the action names for it (duration); it was dropped for the default. With no such field it is said. mergePatchover a value that is not a map drops the patch's nulls (RFC 7386)..lengthof a record or of a value not known at expand stays.length.
Words, repeats and overlays:
- An id built from data on a repeated line (
Row#row-{row.id}under an each) is refused: the line has no id, and the issue names the fixed id to write (its copies arerow#0,row#1…; an action reaches one by its item,scrollTo node=row item={i}). It was read as its fixed part without a word. - In a
define, a bare name that is a parameter or a variable stays one where an id of that name exists (if expandbesideGlyph#expand);{props.size}is the word's own parameter; a record key named like a parameter is kept; a parameter written where an action goes (onTap={save}) is the use's actions whatever its name;@querywithparam @querybindsprops.query. GridView data={…}is a grid over the data, its line the cell. An each under a ListView or in a Stack whose lines are several nodes makes them one item; the list repeated the first only. A ListView with lines beside its each and anonRefreshstays a list, and pulls.- An overlay line's route fields (
Sheet#s maxHeightFactor=0.9 showDragHandle=false,Dialog#d barrierDismissible=false,enterScale=0.6on a Menu or Popover) are what every open of it says; they were refused as the column's keys. - A run written with
"text"and nostartis that text where the line first has it. A component call keeps its radius and clip.
- Links in a text. A run's
linktakes the tap:onLinkTap(triggerlinkTap; resultlink,text,start,end), else the link opens.regexMatches(text, pattern)gives[{start, end, text, groups}], anda ?? bis the null fallback, so a text's links can be worked out from what it says. - Pictures that stretch and shapes that clip.
ImagePaint.centerSlice(centerSlice=andscale=on an Image line) stretches a picture from its middle.Decoration.clipPath,clipViewBox,clipFitandclipCutscut any node to a shape, a Text, an icon and a picture included, asshapeandclip=now do. A linear gradient takesangle; a drawing's paintblurRadius. - Shown over everything, and in sequence.
presentation=banneris a banner over the page and its overlays, queued, closed aftercloseAfterMs.animate=… after=<id>starts an animation when another node's ends, andcurve=beside a preset names its curve.transition property=layouteases a node's width and height, andproperty=decorationa text field's. - Lifted elements.
hero.flies=liftlifts a node out of its page over a new one and back to where it is, and a long press takesholdMs,commitMsandhaptic. - Lists that hold their place. A ListView's
stickToStart,jumpToLatestandrefreshStyle(disc,spinner), also on aneach … followline. - Snapping lists and custom controls.
snapPhysicson a ListView, GridView or PageView; a PageView'sperspective;motion.translateZ;pageOffset, a row's distance from where its list snaps;Trigger.focused(onKeyDown(key=…, focused=true));SwitchProps.thumbWidth;onChangeStarton a Slider;overscrollin a scroll's result;result.cancelledondragEnd. - The device's edges in formulas:
screen.insets.top,.right,.bottom,.left,screen.keyboardandscreen.textScale. - Text and fields:
TextStyle.fontFamilyFallback,enableSuggestionson an Input, input formattersemailandphone,Stickyfrom a number, andconcatof texts gives a text.
The expander names what it cannot read: an overlay with nothing under it, a ListView with data= and an each
under it, a place past a hugging Stack's edge, a state named index read inside an each, showDragHandle=false
beside snapHeights, an input formatter of a kind no field applies, a run's text the line does not have, curve=
alone or misspelled, after= without animate=, blurRadius without a paint, a bad centerSlice or scale,
and a formula function that does not exist.
The notation reference gains pages and examples for what writers looked for and did not find: sizes of controls side by side, text runs and links, lists in a chat, pickers and wheels, overlays in sequence, clip shapes, and the device's edges.
The notation's chart words draw finished charts from one line: LineChart, AreaChart, BarChart, Donut and
Pie write their look as keys of the chart they stand for. A chart, barChart, lineChart, plotChart or
graph node that leaves a key out is as it was. With CodelesslySDK 40.2.0.
Each of these is a key the word writes on its node (the line's own key wins, and a node written by its type,
chart, barChart, lineChart, takes none of them):
- Several series (
LineChart,AreaChartorBarChartwithseries=, or aLineChartwithlabels=):selectOnHover=true tooltip=true(what is under the pointer is selected and says its value),legend=true,roundScale=true(the scale ends on labeled lines),plotInset=6,axisFontSize=11; lines alsodots=12(a dot on each of up to 12 points) andcursorLine=true, each series"curved":true, anAreaChart's"fade":true; barsbarRadius=4 maxBarWidth=40. - One line of values or of rows (
LineChart values=[…],LineChart data={rows} …):smooth=true, a clearareaTopColor(no fill under a line;AreaCharthas the fill),scrubEnabled=true cursorLine=true,gridValues=true(round lines with their figures). It was a straight line over the node's soft fill, with no figures. ASparklineis as it was. - One series of bars (
BarChart values=[…]) is drawn as a chart of several series is:gridValues=truewithgridLines=4 gridLabelWidth=44(the chart chooses its round lines and writes each one's figure, also for values that follow the state; the word wrotemaxandgridLabelsworked out from written values, and nothing for bound ones),labelFontSize=11,labelFontFamily=""(the page's family),labelAreaHeight=22,tooltip=true.max=orgridLabels=on the line keep the chart's own scale. - A
Donutor aPie:selectOnHover=true tooltip=true axisFontSize=11,legend=truewhere it has labels, and for aDonutcenterLabel="Total"(its total in its hole:total="Visitors"names it,total=falseleaves it out; none in aStack, where the page's own text is over it). - One Donut legend. The chart draws its labels and their shares itself, beside the ring where its box has the
room and under it where it has not, on every canvas and for lists written out or following the state. The word no
longer writes a row of nodes for it on a page. A Donut with a legend is as wide as what it is in and 200 high
when no size is written (the square it was in a
Row, withlegend=false, or with no labels); a page that writes the labels itself keeps its own legend, as before. - Colors are left to the theme. A series or a slice whose color the line does not write has none in the
document: it takes the theme's next series color where it is drawn (
colors.chart1,chart2… where the theme names them, else its accent followed by colors of other hues), in light and in dark. The word wrote the accent and lighter and darker steps of it.colors=[…]and a series'"color"are as written. BarCharttakesseries:BarChart labels=["Q1","Q2"] series=[{"name":"2024","values":[30,42]},{"name": "2025","values":[36,45]}]draws each label's bars side by side, andBarChart stacked …one on another. The series follow the state in braces, as aLineChart's do.series=on aBarChartwas left out.
chart:legend(under a plot, a key for each of two or more named series; for a donut each labeled slice with its share, beside the ring or under it),roundScale,dots(a dot on each point of a line while the chart has that many rows or fewer),cursorLine,centerLabel(a donut's total in its hole, this text under it), a series'fade.plotInsetis read: room over the top line and at each end of a line.maxBarWidthis read and is unset by default (it said 36 and was not read): each bar of a group is at most that wide.lineChart:gridValues,cursorLine,tooltip(true: withscrubEnabledthe point says its value, as before).barChart:gridValues,tooltip; alabelFontFamilywritten empty is the app's own family.graph:legend(show:none,auto,always;position:auto,bottom,top,right;values),style.palette(the colors of the marks that write none, in turn),style.ink,style.tooltip,tooltipTextandtooltipBorder,xAxis.inset,xAxis.maxBarWidth(the graph read it; the record now has it),yAxis.nice, a mark'sdots,centerandcenterLabel.chartPalette("#FF2563EB")(andchartPaletteOf(0xFF2563EB)): the eight colors of a chart whose accent is that one. The accent first, then seven colors of other hues, each about as light and as strong as it (a yellow a little lighter, as yellows are); an accent with no hue (a black, a gray) is followed by colors of a moderate strength.
- A tooltip's ground is the surface the chart is on with a hairline round it, its text the surface's ink
(
tooltipColor,tooltipTextColor, a line chart'stooltipBackgroundwhen not written); it was an inverted surface.
- A bare
Slotin a component that declares slots and takes no children is the slot the call's lines fill. It drew nothing. ASlotthat names a slot the component does not declare is an issue. - A box with a fixed height keeps it when a child fills it, whichever order the child and a text are written in.
growon a box in a Column fills the height left. It was 0 high.xoryon a line under a Column or Row is an issue: only a Stack places its children.- A state word on a line that is also a variable's name (
pressed) is an issue, once a document. - The reference says that controls in a row share a height, what a negative place and a fill do in a Stack that
hugs, that
nullinsite.jsonis a text variable, a regex's inline flags, and the width a site is expanded at.
The open prompt (notationPrompt(open: true)) teaches more of what the notation already has, at the same length;
the taught prompts (open: false) are as they were. Lines of the notation that were read by nothing, with no word
said, are read or said. With CodelesslySDK 40.1.0.
- A state written as a formula with no type (
state limit={pick == "15 min" ? 15 : 100000}) is read by a function, by a typed formula variable and by a drawing's lines, wherever it is declared. A function that read it compared against nothing (its list was empty), and aparagraph "Peak {total}"drew no value. - A function with no type (
state fits(c)={…}) is said, with the line to write (state fits(c):boolean={…}); it said only that state is writtenname=value. - A
customPaintline's own key that is worked out (viewBox=[{length(rows) * 10},100]) is said and left out: the painter's keys are values. It was kept and read by nothing, and the drawing was in the box's pixels. - A chart's lists follow the state.
LineChartandAreaCharttakelabels={…},values={…}andseries={[{"name":"Visits","values":map(rows, r => r.visits)}]}(a part of a series may be in braces of its own); aDonuttakesvalues={…},labels={…}andcolors={…}. Each was left out, the Donut drawing a grey ring. The chart's rows are worked out from them (props.datais bound). A Donut whose lists are worked out draws no legend of its own. Aseriesthat is one variable is said: how many lines it has is not known. - A chart over rows.
BarChart data={rows} xField="day" yField="count"reads its values and labels from those fields (it drew nothing and refusedxField);AreaChart data={rows} …fills under its line. - The reference's page on a design at a width says what a
Row's block lines do: they are side by side, as its own are, and aColumnin the block orphone.direction=verticalon the row's line puts them down the page.
- Drawing. A page's open prompt teaches a
customPaintline under aBoxwith a line per shape (rect,circle,path,linein an example;rrect,oval,arc,paragraph,repeatnamed), so a picture is drawn and not stacked from boxes. The lines arenotationPaintLines. A card's open prompt (under 700 wide) does not have them. - A value worked out and a function of the writer's own.
state total={price*qty}, andstate fits(c):boolean={…}with its type, used asfilter(cards,c=>fits(c)). at phone. Where rows side by side are taught, a block of the part's lines on a phone with...#idplacing a line again, in an example, andphone.gap=8for one value that differs. The lines arenotationAtPhoneLines.- Keys. A
Selectand aSegmentedButtonkeep the chosen item in@name; a chart's lists follow the state in braces (values={…},labels={…},series={[…]}); a main string from a variable is quoted (Icon "{c.icon}"); a text with braces of its own is a formula's string (Text "{'if (x) { y }'}"). - Left out to make the room: the events of a design system's
SiteNav(its line in the list of words that already exist names them); a table written as rows of fixed-width cells; a sidebar's item and a sidebar's contents in prose (the app example shows them);Row betweensaid a second time; the JSON ofsite.json's variables; three sentences that restated what reflow does or what an example shows; and shorter wording for aDonut's legend, a galleryLightbox,hide=/show=, a sticky rail,goandscroll.
Lines of the notation that looked right and drew wrongly now draw what they say, and what a page names wrongly is said. With CodelesslySDK 40.0.0.
What a page written once draws on a phone and a tablet, and what a plain line draws by default: rows that stack where they have no room, one rule for a bar on a phone, a table's and a grid's columns, a website's type scale, and words the notation refused. With CodelesslySDK 40.0.0. Most of this changes how an existing document draws: read the first section before upgrading.
- A
defineof a name the notation reads as another of its words is the one read.define MonthGrid …,define DataTable …(names that were read asCalendar,Table) are the page's or the site's own word, as a definition already is over a dictionary's; the definition was left unused and said. Aprimitiveof such a name is still not used (it has no lines to draw in the word's place), and a definition of a word the notation has itself (Card,Rail,Footer) is still not used and said.notationBuiltInWordtakesprimitive:and no longer names an alias for a definition. - A state whose value reads an element by a key is a formula.
state piece=stories[story],state first={rows[0]},computed current=rows[at].namewere kept as a text holding the expression; they are the value now, asstate n={length(rows)}is. - A component's parameter read by its bare name in braces is the component's. Under
param edge=180,w={edge},"{edge}",if fluidandeach row in rowsreadprops.edge,props.fluid,props.rowswhere no state of the text and noeacharound the line has the name; they read nothing.props.edgereads as before. clip=trueclips (it isclip, an anti-aliased clip;clip=falseis none). It was kept as written, which clipped nothing.- Two sides of a border on one line are both drawn (
border-right=rule border-bottom=rule): the second replaced the first. A second side of another colour is drawn in the first's and said. - A box pinned to both edges of its Stack along an axis with no size there fills between them
(
y={"start":12,"end":2}with noh): it hugged its content, and a box with only a paint under it had none. fill=on anIconButtonis the button's own ground (style.backgroundColor), which it draws; it was written on the node, where a button draws nothing.- A
Selectwhoseitemshave a value and a label (items=[{"value":"system","label":"Match device"}]) lists the labels, shows the label of its value and gives the value when one is chosen; it showed nothing. ASegmentedButton's such items are its segments (it showed the records as text). Select … selected={x}is read asvalue={x}, and says so:selectedis a node's selected state, which a Select does not show.LineChart series=[3,5,4]is one line's values, asvalues=is.phone.gap=,phone.mainAxisExtent=andphone.childAspectRatio=on aGridare the cells of the grid itseachmakes at that width; they were left out.- A bare word after
gothat is a page of the site is that page also under aneachwhose item has the name (each album in albums/go album) and in an overlay; the item, or a variable of the name, was gone to instead. The item isgo {album}. - A bare word given to a parameter that names an icon or a page (
Brand "Postbox" icon=mailwhere the page has a state calledmail) is the name, as it is on a line of the notation's own; it was bound to the state. A text state of the name could be meant, so that is said with what to write (icon={mail}). Aneach's item of the name is read as before, and a parameter that is no name reads a variable as before (bpm=bpm). theme.<name>in a page's expression is the theme's color of that name (fill={on ? theme.ember : theme.line}readstheme.colors.ember), or, where the theme has no such color, the look the notation's own words take (theme.accent,theme.line,theme.mutedInk: what a defined word's lines read). It read nothing: a theme's colors are undertheme.colors. The theme's own values (theme.primary,theme.isDark,theme.text…) read as before.- A place or a size read from a text that is one value is the number (
x={"align":"{p.mapX}"}, also written"${p.mapX}"): it was the text"$0.6", which is no place.
Rows on a phone and a tablet
- A Row whose child is written as wide as its place at a width is laid out down the page there.
Column w=345 phone.w=fillbesideColumn grow, orSelect w=180 phone.w=fillin a filter row: on a phone each such child, and each child that grows, takes a line of its own; buttons and labels between them share a line; aSpacergoes. The row kept its line and the child that grows had no width left. A Row that says its ownwrapordirectionthere, has a height of its own, scrolls or is writtenkeepis as written;phone.growon two buttons still shares one line. - What grows in a row keeps a width its words can be read at on a phone. A column of text that grows keeps up to 200 (a text alone 160): two columns of paragraphs take a line each, where each had half a phone. In an app's pane a column that grows counts for up to 120 when a row is fitted to a phone, so a heading beside a box of figures goes above it. A label of two short lines beside a button keeps its line, as does a list's row.
- Copies that grow from a least width in a row written
wrap(Row wrapover aneachofCard basis=265 grow) are a grid of as many equal columns as fit at that width (minCrossAxisExtent), and the copy'sphone.basis=is the least width there. They were one column to a copy at every width. - The cells of a
Gridthat are as tall as their row hug where the grid wraps: a board's lanes had no height on a tablet and a phone. - A
Gridwhose columns are worked out (cols={zoom}) shows at most three on a phone.
Bars
- A page's bar is one line on a phone: its brand, its icon buttons and the menu button. Where its other
labelled buttons (
Button.outline "Get a valuation") have no room beside them, they are in the menu with its links, each as its own kind of button as wide as the menu; they stayed in the bar and pushed it onto two lines. A short brand and a button that fit keep the button in the bar. A bar whose links are in its menu does not wrap. A bar with no links is unchanged. A button that says where it shows, or stands under anif, stays where it is. - A second
Navin a page is a strip: it keeps its items at every width and scrolls sideways on a phone. It folded to a lone menu button. - A
Navamong the lines of a defined word (define ShopHeader/ a notice /Nav) is the page's bar where the word is used: the page's gutter and width, its links in a menu on a phone. It was a bare row from edge to edge. maxwon aNavin a component is how wide its items spread, in the middle of the bar; it was the bar's own width, anchored at the left.- A quiet button in a bar that goes to the page shown is drawn selected (
Button.ghost "Speakers" onTap={go speakers}on the speakers page), unless the line saysselected=. On a website a bar's quiet buttons are 15 semibold. - An app's sidebar button: where Main's
Navis written after a line that draws nothing, the button is in that bar and the slim bar made for it is not drawn (there were two bars). Where the page writes its own button for a narrow window (IconButton "menu" show=phone onTap={open …}), no button, bar or drawer is made for the sidebar. - The menu of a bar that is the last thing written (a component whose body is a
Nav) starts closed; it was drawn open.
Panes, tables
- A
SidebarorPanewhose width is kept in a variable (w={sidebarWidth}) is hidden on a phone, and on a tablet where a second pane has no room, as one of a written width is. - A
Tablefits its columns to a phone and a tablet also where a column is left out by hand ("hide": "phone"): the columns that still have no room beside the one that grows are left out, and on a phone a wide column of data (150 or more) narrows to 90 first. The column that grows had no width. - A row with a part that grows, written in a
Tablecell, is as wide as the cell.
A website's type
- Under a
Pagea Text takes a website's size wherever it is written (aSection, a column of the page's own, a card), not in its bar:heading1andpageTitle64 (they were 60, and 30 outside a Section),heading238 (24),heading324 (18),title22,heading18, a plain Text andbodySecondary,muted,strong16 (13 and 12),smallandmono14,caption13. On a phoneheading3andtitleare 18, and the headlines smaller in proportion as before. A line that says its size or style, a style the theme gives a size, and every style drawn from abodythe theme sizes are as before. An app's sizes are unchanged. - A
Section tinthas a ground when the theme names noband: a tenth of grey over the page. - A Column, Row or Stack written
maxw=straight in the column that scrolls the page stands in the middle of the room left, unless the line or that column says a side.maxWidth=by its field's name is the bound alone.
Controls
- A Toggle, Checkbox or Radio in a row that already shows its string as a text draws no label of its own: the
string is its spoken name (
semanticLabel). - An
Input type=numberwith no width in a row is 96 wide (240 before). - A field's label is its hint beside chips in a row, and in a row of a set height under 56 (a formula bar), as it is beside buttons.
-
The
graphnode type: rows drawn as marks (bars stacked or side by side, lines, areas, candles, slices), on rows one place each or a linear x scale, with ticks, guides and a selection (hover, tap) it publishes throughchanged. Its parts (xAxis,yAxis,marks,guides,panes,transforms,selection,crosshair,interactions,style) are typed records, so the notation reads their fields as dotted keys and checks them. The chart types (chart,barChart,lineChart,plotChart) keep their declarations; the SDK draws them as graphs. -
SiteManifest.now("now": "2026-11-16T09:00:00"insite.json): the time a site's seed data is written for. The render and states commands read it as their--nowwhen none is passed, so a calendar, a countdown or a "due today" is drawn on the day its data means. A running app does not read it. -
unknownThemeColors(document, theme): the color names a document's nodes use that a theme does not have, each with the nodes that name it. -
A bound size takes its fit as a word: a binding of
layout.widthorlayout.heightthat gives"fill"or"hug"is that fit (w={fluid ? 'fill' : edge}); it read as no size. -
fillonButton(any kind) is the button's own ground, with a label that reads on it unless the line givescolor. It was kept on the node, where a button draws none, and the button stayed the theme's primary. -
radiusonButtonandIconButton: the corners of the button's shape (Button "Donate" h=44 radius=22). It was refused. -
phone.axis=verticalandphone.direction=columnon a Row or Column read asphone.direction=vertical.axiswas refused.
- A defined word whose body is an overlay is that overlay wherever its use is written.
define SideMenuoverDrawer#menu …, called in the page's tree or after it, with or without an id, is the draweropen menushows (the body's id, or the use's when it has one); its lines were drawn in the page. Ids of defined words inside it no longer repeat the page's. - An overlay's word with no id inside an overlay (a dictionary's
ConfirmDialog "…" "…"written underDialog#sure) is that overlay's content: its title, its note and its buttons. It was "No node type Dialog". - A
Table row in rowsin a definition reads the use's list whenrowsis a parameter; it kept the parameter's name, which nothing has, and drew its header only. - A
Footeramong a defined word's lines under aSidebaris the sidebar's foot, as it is written there directly; it was "No node type Footer". - A state's words that make a Text another kind of node (
Text … selected={…} selected.fill=tint) no longer take the text away while the state holds; the look is kept, and what to write is said (the box, with the state on it). - An overlay's
go pagenames a page of the site as the page's own lines do. - The reference's example for
regexReplaceshows a group as$1(it showed\$1).
- A state written twice, or a state and a
computedof one name: said at the second, with the line of the first. - A
LineChart'sseries=that gives no values, and itslabels=with no values to go under: said, with what to write (series=[{"name":…,"values":[…]}],values=withlabels=,xField=withdata=).
- The reference's responsive page states each rule above; its pages for navigation, forms and charts state the website's type scale, a bar's links, the label rules and a bar chart's widest bar.
Schema 3 is the only schema the package reads, and three things a page could not say: which stop an open sheet rests at, a file picked on the device without uploading it, and the device's share panel with the page's own address. With CodelesslySDK 39.0.0. Read the first section before upgrading.
Schema 2 documents are refused
- Documents of schema 2 are no longer read.
LayoutDocument.fromJson,PublishLayout.fromJson,PublishComponent.fromJson(its document),PublishModel.fromJsonandPublishBundle.fromJsonthrow anUnsupportedSchemaException(aFormatException) for JSON of any schema other than 3, saying the schema it found and the one it reads:The document is in schema 2; codelessly_api reads schema 3 only.(The publish model ...,The bundle ...for those). - What to do with a schema 2 document: convert it with 38.0.0 before upgrading. 38.0.0 is the last release
that reads schema 2: load each document, publish model and bundle with it (
LayoutDocument.fromJson, ormigrateJsonon the JSON) and save whattoJsongives, which is schema 3. Then upgrade. 39.0.0 has no converter. - A document with no
"schema"is refused too (it was read as schema 2):The document has no "schema"; codelessly_api reads schema 3 only ("schema": 3).A bundle may leave its ownschemaout, as before; its model and layouts carry theirs. JSON that is not a map still decodes as an empty document or model. printNotationprints documents of schema 3 only, refusing any other with the same exception. The notation no longer writes or readsdocument schema=2: adocumentline takesschema=3or noschema.- Older spellings are no longer read: a submit-form action with the removed newsletter settings and no
serviceis a local submission; a text field'svalidatorgiven as an object ({"type": "required"}) reads as none; a node'scomponentmarker{"marker": "component"}is an instance (write"role": "main"); a signature pad'ssignLineOffsetandshowSignMarkare gone (writesignLineBottomandsignLineMark).
Sheets
- A
Sheetwhose highest stop is over nine tenths is as tall as that stop (stops=[0.5,1]reaches the top of the window): itsmaxHeightFactoris the highest stop. It was 0.9 whatever the stops, and a stop above it was dropped, sostops=[0.5,1]had the one stop. A sheet with no stop over 0.9 is unchanged.
The share word
sharein an event is the share action (onTap={share url={screen.url}}). A page that wrotesharethere for something of its own had an unknown action, said as an issue; it now opens the share panel.
-
The stop a sheet rests at, in a variable.
Sheet#story "Title" stops=[0.5,1] stop=@sheetStop(the open action'sstopVariable, a variable's name) binds the stop both ways. The variable holds the stop asstops=writes it (0.5,1): the sheet writes it as it opens and whenever it is dragged, or moved by its handle or the keyboard, to another stop; setting it (sheetStop=1) moves the open sheet to the nearest stop (and the variable takes that stop); a sheet opened while it holds one of its stops opens there, else at the lowest. It is0while the sheet is closed. The variable is declared (state sheetStop=0);stop=given anything but@name, or on a sheet without stops, is said with what to write.state sheetStop=0 Column gap=12 Button "Read" onTap={open story} Sheet#story "The tide tables" stops=[0.5,1] stop=@sheetStop Text.muted "A summary" visible={sheetStop < 1} Button.ghost "Read it all" visible={sheetStop < 1} onTap={sheetStop=1} Text "The whole article" visible={sheetStop == 1} -
pickFile: a file picked on the device, given to the page, uploading nothing (PickFileAction, in the media library besidedownloadFile).resultis the file's record,{name, size, type, data}:sizein bytes,typeits MIME type (""when unknown) anddatathe file as adata:URL, which an image shows and acloudFilesaction takes as itssource(so does the record). Fields:accept(the kinds offered, as HTML'saccept:"image/*,.pdf"; empty for any file),multiple(resultis then a list of records),content(dataUrl, ortextfor the file's text in place ofdata, ornonefor neither) andmaxSizeMB(10). A file of another kind or over the size fails the action (invalid-file-type,file-too-large); when nothing is picked the actions after it do not run.state files=[] Column gap=12 Button "Attach" icon="attach_file" onTap={pickFile accept="image/*,.pdf"; files=append(files, result)} each f in files Text "{f.name} ({f.size} bytes)" -
share: the device's share panel (ShareAction, in the media library), with atext, aurland atitle, each an expression.resultis{shared, copied}: where there is no share panel the URL (with no URL, the text) is copied to the clipboard andcopiedis true; both are false when the person closes the panel.share title="Trip notes" url={screen.url}; result.copied ? toast "Link copied". -
screen.url, the address of the page as shown, is named in the reference (codelessly_sdk gives it: a browser's URL; in an app the location a link opens the screen with, or empty). -
The reference has each:
stop=@nameandscreen.urlinnotation/navigation.mdandnavigation.md,pickFileandshareinnotation/media.mdandmedia.md, each with an example. The open prompt's line for aSheetnamesstop=@atbesidestops=. -
UnsupportedSchemaExceptionandrequireSchema, exported withkSchemaVersionfromcore.dart.
- The schema-2 reading:
migrate2to3,migrateDocument,migrateJson2to3,migrateJson,migrateNode2to3,migrateNode,migratePublish2to3,LayoutDocument.migrateSchema,PublishModel.migratePublishSchema,schemaMigrations,publishSchemaMigrations,SchemaMigration,MigrationReport,MigrationEntry,MigrationEntryKind,jsonEncodeShort,migrationReportMarkdown,MigrationStep,MigrationScope,schema3Steps,isLayoutDocumentJson,dropNaturalLineHeightFlags,copyJson,schemaOf,kOldestSchemaVersion,schema2PathHint,movedPathHintandolderSchemaPathHint;AnimationPresets.legacyMotionProperties;Track.frictionRate;SignatureProps.signLineOffsetandSignatureProps.showSignMark. - The guide's chapter on migrating to schema 3 and the old shapes in its animation and gestures chapters;
docs/design/schema-3-migration-report.md.
A part's own design at a width (at phone), more of what a define can say, dictionaries of definitions in
place of the notation's shorthand words, and fixes to lines that followed the notation and drew wrongly: lists,
grids, rows that wrap, an app's bar, a Nav on its own. With CodelesslySDK 38.0.0. Some of these change how an
existing document draws: read the first section before upgrading.
The shorthand words are no longer the notation's
- These words are gone from the package:
Heading,H1,H2,H3,H4,Title,Brand,Logo,Link,NavItem(andNavLink,SidebarItem,MenuItem),NavSection(andNavGroup,NavLabel,SidebarSection,SidebarLabel,SidebarGroup),SidebarFooter(andNavFooter),IconTile,Dots,ConfirmDialog,Shortcut(andshortcut) andcomputed. A page that writes one without a definition of it has an unknown word there: an issue, or a placeholder with the open vocabulary. A design system's component of one of these names (Desk'sNavItem,Brand,MenuItem,NavSection) is called as before. - To keep writing them, give the page a dictionary that defines them: a folder of definitions, one
<Word>.txteach (define NavItem "label" icon badge selected=falseand its lines), read withNotationOptions.dictionary(or--dictionaryand a site's"dictionary"key, with CodelesslySDK). The definitions, ready to copy, are in the notation reference (docs/reference/notation/components.md, "The shorthand words of earlier versions"). Each is a plain definition in base lines with one meaning, so a page written with them draws as those lines do, the same wherever it is written:Heading,H1–H3areText.heading1–Text.heading3,H4isText.strong,TitleisText.title. In an app a level-1 heading took the app's title size (20) and a website's level 2 and 3 took display sizes (36, 22); they take the theme'sheading1–heading3now (a website'sheading1in aPage'sSectionis still at a display size).Brandis the product's mark as a sidebar draws it (an icon on an accent tile, the name in bold, a line under it); at the start of a bar it had no padding and a larger name.NavItemis a full-width row with an icon, its label and a count, the chosen one on a tint of the accent. In a bar the items sat side by side; the chosen one's label took the accent;shortcut=showed a key at its end.NavSectionis a label in small spaced capitals;SidebarFootera spacer and a column under a rule.Linkis its label in the accent, opening its web address or scrolling to#part; in a bar it was a quiet button the bar's phone menu repeated.IconTileis an icon on a tinted square,Dotsa row of page dots,ConfirmDialogaDialogwith a Cancel and a Confirm button (danger=truefor a red yes),Shortcut "mod+k"akeyline,computedastateline.
- A sidebar made a rail at a width no longer hides its items' labels there: that was these words' own
behaviour. Write the rail's lines for that width (
at tablet), or icon buttons. - A
Nav's phone menu repeats its quiet buttons (Button.ghost "Pricing" onTap={…}), each closing the menu and doing what the button does: it repeated the bar'sLinks.menu=falseis gone withLink. - A drawer closes on a line tapped in it (a row, a text, a component), and on a control (a button, a chip, a
toggle…) when it goes somewhere (
go,scroll,link,open): a filter cleared or a choice made in the drawer keeps it open. It closed on aNavItemor aLinkonly. - A website's section is a hero when its headline is a
Text.heading1orText.pageTitle: it was when it had a level-1Headingor anH1. - The alias table's line rewrites are gone (
TypeAlias.line): an alias is another name for a type of the notation; a word of another shape is a definition.
Rows, lists and grids
- A row that wraps has its gap between its lines too (
Row gap=12 wrap,phone.wrap=true), as CSS'sgapdoes, unless it saysrunSpacing; its lines touched. A document made before printsrunSpacing=0. - A
ListViewwith lines of its own (a line beside itseach, or noeach) is said at its line and read as the scrolling Column it is:Column scrollwith the lines and theeach. It repeated its first line without end, or drew nothing when that line was hidden by itsif. A list with words a Column does not take (stickToEnd,reverse,separator…) keeps them and has one item, a column of its lines. - An
eachacross a row of a height of its own (Row h=102over the days of a week) makes copies as tall as the row, at each width the row gives a height, so a copy writtenh=fillfills it. They hugged their content, centred in the row. Across a row with no height of its own the copies hug as before. - The copies of an
eachunder aGridtake the cell their line says:columnStart,rowStart,columnSpanandrowSpanwritten on the one line under theeachplace the copy (every copy took the next free cell), and a grid whose copies say their column keeps its columns at every width. Two or moreeaches under one Grid whose copies all say their cell are one grid (a timetable's times and sessions); they were grids one under another. - A row whose growing texts end in an ellipsis keeps its line below a desktop's width (a name and its role,
maxLines=1 overflow=ellipsis, beside an avatar): the texts give way. It wrapped where it had no room, the avatar above the name in a narrow sidebar, most often in a component's definition, which is laid out as a page's rows are.
Bars
- An app's bar shows the page's name beside its menu button where the sidebar is a drawer and nothing in the
bar names the page at that width (a
Breadcrumb … hide=phone): the name itscanvasline gives, taking the bar's room. The bar had the menu button alone. - A
Navout of a page's frame (in a component, or a column of its own) is a bar: its lines sit side by side at their own widths, and on a phone it goes onto a further line where it has no room (unless it says how it wraps). Each line took an equal share of the row, one letter a line on a phone.
Cards and components
- A flip card (
flip.axis=…) of more than two lines is said at its line: its first line is the front and its second the back, so a second of three lines was hidden as the back (the word on a study card). Where its lines are shown by anifand itselse, they are read as the two faces, a column of each. pad=on a component call is an issue and left out: the room inside a component is its definition's (the renderer draws the root's padding), so it was taken and drew nothing. A strict expand of such a text now fails; the drawing is the same.
Defined words (define)
- A value a body works out from the use's written values is worked out as the use is read.
radius={size/4}withsize=40isradius=10,"{upper(label)}"is the label in capitals,Text.{level == 1 ? "heading1" : "heading3"}is the variant, and anif(with itselse) that reads only written values keeps the branch taken and writes nothing for the others. A call worked out from written values inside an expression that still reads the state is worked out too ({on ? "#FF2563EB" : coalesce(null, "#FF6B7280")}); an expression that reads the page's state is read at run time, as before. Nothing draws differently; a document built from a definition has fixed values where it had bindings of the same values, and no hidden line where anifwas false.
The prompt
- The prompt (
notationPrompt, open and full) no longer teachesWanted,ListorContent: its list of types namesRowandColumn(it gaveBadgeandWantedas their names), "Only Row, Column, … take children" no longer namesList, and the wordContentis gone from its text. The words still expand as before;notationPrompt(wanted: true)still asks for a missing component with aWantedline. Its text no longer writesLinkorDotseither, two of the shorthand words above.
A design at a width (at <width>)
A part whose lines differ at a width, and not only its values, writes its design there in a block under it, after its own lines:
Row#bar w=fill between middle
Text#brand "Acme"
Row#links gap=24 phone.direction=vertical
Button.ghost "Pricing" onTap={menu=false; scroll pricing}
at phone
Column w=fill
Row w=fill between middle
...#brand
IconButton "menu" onTap={menu=!menu}
if menu
...#links
at <width>under a node line: the lines under it are that line's children where the width holds; its own lines show everywhere else. The width is any condition a key's prefix takes (at phone,at tablet,at desktop,at max899,at min700.tablet,at portrait;at mobileisat phone). The part's own line (its id, its keys, its events) holds at every width....and...#idin a block: the part's own lines, or the one with that id (at any depth, with the lines under it), read again there. Each is a second node, its id<id>_<width>(links_phone,search_min700_tablet); an action that names the id (focus search,scroll pricing) is written for each copy, so it reaches the one shown. The copies share their bindings and a defined word's own state.- Several blocks hold in the order written, the later winning where two hold: write the wider first. A width no block holds shows the part's own lines.
- Reflow leaves a block's lines as written, and still fits the part's own lines where no block holds (the hide rules a block gives them do not make them the writer's); what it gives the part itself is undone where a block holds.
- Page words: under a website's
Nav(orHeader,TopBar) a block that holds on a phone is the bar there, and the Nav writes no menu of its own; under aTablethe block's lines go in its frame in place of its header and rows,...its cells (a list of cards on a phone); an app'sSidebarwith a block is still its drawer on a phone, with its own lines; an app'sNavwith a block is the writer's whole bar where the block holds, and no page name is added there. - Said, and not read:
atat the margin, under aneachor anif, inside another block, in a definition's lines, underApp, under aGrid, under a line that takes no lines, with a breakpoint's name (at minTablet), a block a later one shadows, a...#idno line has, anything written on a...line, and a part's line written after its blocks. Each says what to write instead. - Expanded to what renders today: twins with media rules, no new node or property. The first line of each
block is named
at <width>;printNotationreads that back and prints the block, a line read again as...#id(or...). Twins written by hand print as twins. - The prompt teaches it in one sentence where widths are taught; the reference's responsive page has a section on it.
Defined words (define)
...as a word of a body line marks the line that takes the words a use writes beyond the signature: the universal words, and every other key, flag or event, read there as on a page's line (they were recorded as words the definition does not have). The root keeps the use's id.- A body's lines may carry a role (
Row~app,Column~section, …): the reflow lays them out at a tablet's and a phone's width as it does the page words'. A role on a body's root was refused. - A word may stand for a statement: a body of
key,stateoreverylines alone is those lines where the use is, and its word may be lowercase (computed total={…}overstate ...).key {…}in such a body takes the chord worked out from the use. - A body may read the theme as
{theme.<name>}: the looks the notation's own words take from the theme (accent,line,paneFill,mutedInk,contentWidth,sectionPad, … andtheme.style.<name>, a text style's name when the theme has it), worked out as the word is used under whatever theme the page is read with. A look the theme does not give leaves its key out; any othertheme.name is read as the page runs; a name that is neither is an issue that lists the names. - More of a body reads the use: an event of a trigger with fields (
onKeyDown(key=c)={onCompose}), anon …line (on valueChanged(variable=x)={onSeen}, before the body's root too), and a variable a key names by its name (measure.variable="box", the word's own when its body states it). An action's field named like a parameter (downloadFile text={text}) keeps its name.
Dictionaries
NotationOptions.dictionary(texts, name:)reads a dictionary: a folder's definition files (<Word>.txt, each adefineor aprimitive) by file name, and the folder's name. Its words are read after the page's own definitions and the site's or the design system's, and before the notation's own words; of two dictionaries the later given is read first.NotationVocabulary.withDictionaryandNotationVocabulary.dictionaryare the same on the vocabulary.- The vocabulary record names the dictionary a word was read from: a use's
ofis the folder's name, andnotationWordOrigin(word)says where a word's meaning is written:base(the renderer and the parser), the dictionary's name, orcode(a word of the page's frames, written out in Dart:App,Section,Nav…). - The prompt lists a dictionary's words after its own, one line each as a line uses it with what it is for
(the first sentence of the comment over its
define). With no dictionary it teaches the base lines: a row per sidebar item,Text.heading1–Text.heading3, a quiet button in a bar. - A definition written at the margin with an id that stands for an overlay (
ConfirmDialog#ask "Delete?"over aDialog) is that overlay, opened byopen ask. SiteManifest.dictionary: a site's dictionaries ("dictionary": ["../words"], relative tosite.json).- A body's theme reads in a value's text (
fills=[{"color":"{theme.accent}","opacity":0.12}]) are the look as written, andcoalescedrops what the theme does not give (coalesce(theme.accentText, theme.accent)is the accent where the theme has no link ink).
Charts
ChartSeries.withKind.
- A
SegmentedButton … expanded=truewith no width of its own takes its place's width; it hugged its labels and cut them. A document made before prints its hugging width (w=hug). - A component whose root has a shape (
Stack w=fill aspectRatio=1) keeps it where it is called with none (seamCall); a call that hugs its height drew it 0 tall. - Cards side by side in a row that says where its children sit (
Row top) sit there; on a page they were stretched to the tallest whatever the row said. A row that says nothing keeps its cards equally tall. - A line of a length of its own that grows at another width (
w=280 phone.grow) takes the room it is given there; it kept its length and the row ran past the window. - A dotted key in a definition's body reads the use's values (
hovered.fill={tint}); it was left as written. - A record line of a definition (
customPaint,animation) is its body's: written after the page it was also drawn on the page's node open above the definition; written before the page it was refused.
- The notation reference says what was hard to find: plain
keylines wait while a text field has the caret; a list that follows its newest entry (each … follow h=180, the list'sstickToEnd); Enter and Shift+Enter in a multi-lineInputwithonSubmit, as a bullet of its own; looking a word up in the index before adefine;guard=on a Dialog,on valueChanged(variable=…), the keys held on a click (result.shift,result.meta) and a scroll fraction kept in a:decimalstate, each with an example; whatCalendar marks=andBarcode symbology=qrCodedraw; and a condition onscreen.widthin an action for a tap that differs by width.
Better defaults for what the notation draws when a line says little: a website's type and control sizes, a desktop app at a tablet's and a phone's width, text fields beside buttons, charts, and dark mode with no design system. With CodelesslySDK 37.0.0. Many of these change how an existing document draws: read the first section before upgrading.
Websites (Page)
- Headlines are at a display size. In a
Page'sSection,Heading level=1,Text.pageTitleandText.heading1are 60 px (52 on a tablet, 43 on a phone),level=2is 36 andlevel=3is 22; they were 30, 24 and 18. A theme whoseheading1orpageTitlehas a size of 32 or more keeps it, and a line's ownsize=wins. AnApp's titles are unchanged. - Controls are a web page's size. In a
Page, a button, a field and a select with no height written are 40 px (they were 28) with type to match, a chip is 32 (24), the buttons of the Section that holds the page's headline aresize=large(44), and anIconButtonin a Section is a 40 px square in a hairline. A theme'ssizes.controlwins. AnAppis unchanged. - The ground reaches the foot. A
Pageis as tall as the window it is shown in, its canvas takes its fill, and itsFootersits at the window's foot on a short page. Two plain Sections one after the other have 96 px between them (was 128). An app'sMainwith no fill of its own takes its content column's. Section bleedwith no fill has no padding, so what is in it meets the bar above. A bleed band with a fill or a tint keeps its padding.
A desktop page at a tablet's and a phone's width. Nothing here changes at a desktop's width.
- A
Tableleaves out the columns its row has no room for, from the last back. The first column, a checkbox and a narrow unlabelled column stay. A width at which the writer hides a column is left to the writer. - A row of controls in an app's pane wraps on a phone when it has no room: a field of a fixed width takes a share of the line and a spacer goes.
- A list written
Main w=380beside thePanethat shows what it selects is one at a time on a phone, with a back button, or the list alone when no tap selects. - A design system's rail.
sizes.railin a theme makes an app'sSidebarthat writes no rule for other widths a rail that wide on a tablet and a drawer on a phone (NotationOptions.sidebarRail). - A Row written
wrapwith aneachand other lines wraps them all below a desktop's width. - A width rule on a line whose width is bound (
w={listW} phone.w=fill) holds where it says. - An
eachin a row that turns down the page at a width turns with it (Row phone.direction=vertical): its copies stack across the row's width there. - A child written to fill, in a row that wraps, takes the whole line where the row wraps.
- A Grid's columns at a narrower width win over a wider one's, in whatever order they are written:
Grid cols=4 phone.cols=2 tablet.cols=3gives a phone 2 columns.
Text fields
- A multi-line
Inputin a row beside a button is a composer. It starts at one line and grows to itsmaxLines, its string is its placeholder (beside a hint, its spoken name), and withonSubmitEnter sends and Shift+Enter breaks the line. Lines the writer gave (minLines=3) are kept. - One field beside a button draws no label above it: an
Inputin aRowwith aButtonor icon buttons and no other field (add an item, a comment, a stepper's value). Its string is its placeholder, or its spoken name beside a hint. The row that ends a form keeps its label, as do two or more fields in a row and fields with no button.label="…"keeps a label above a field anywhere. - A search field shows a magnifier: a field whose text starts with Search, Find or Filter, a
Searchline, or a field in a top bar whose text or id says search, getsicon="search"unless the line writes its own icon.icon=noneleaves it out. - A field in its own framed row is bare. In a
Rowwith a radius and a border or a fill, beside a button, the field draws no border or fill of its own, and the row's border takes the accent while the field has the focus. - A labelled
Inputof a fixed height is that high in its box, with its label above; the height used to hold the label and the box together.
Decoration on controls
fill,borderandradiuson anInput, aDatePickerand aTimePickerstyle the field's own box. On the node they drew nothing, or a second box.border=nonewith no fill is a bare field. State words work the same way (focused.fill=…).- A
Selectwhose line writes afillor aborderis framed by that box alone; it drew two boxes.
Themes
- A theme's
inkandpaperare its text ink and its ground where it has no design system's names for them. - Dark mode with no design system. What the notation draws by itself (hairlines, cards, a table's band, hover
and selected fills, quiet text, a dialog's and a drawer's panel) is written as theme roles
(
ThemeTokens.notationRoles:line,card,band,subtleFill,hoverFill,quietText,mutedText,faintText,headingText,surface,onSurface). Each role's light value is what was written before; on a dark ground (luminance under 0.35) it is made from the theme's ink and ground. A site that declares light anddarkcolors switches them withsetThemeMode. A color the theme names itself wins. Light pictures are unchanged. - A site's
primaryre-accents a design system's dark accent too. - A theme text style changes only the keys it sets: a style named as a text variant keeps the variant's size,
and
style=serifover a variant keeps the variant's size and ink. - A
Linkis in the theme's accent; it drew a fixed blue. Badge.success,.warning,.info,.primaryand.errorunder a theme with no tints are a tint of the tone's color; they all drew as the neutral badge.
Charts
- Charts with no look from the theme: a
BarChart's bars are apart and rounded over a light grid with figures on the left; aDonut's slices and a multi-series line's colors are steps of the theme's primary; aLineChart's axis is fitted to its data.
Words with no definition
- A stand-in with nothing to draw draws nothing. A word with no definition whose name is a behaviour with no
picture (
KeyboardShortcut,LiveStatus,Clock,ThemePreference) and that gives no size and no text takes no room; written at the top of a page beside itsApporPage, it no longer displaces the frame. Other stand-ins keep their labelled box, and the vocabulary record keeps every use.
Other
- The strings of an
ExpansionTileare its header; they were its first children under a blank header. - A look written on a component call is an issue (
fill,border,radius,shadow,clip): a call takes a size, a place and a margin, and its definition has the look. A strict expand of such a text now fails; the document is the same. - A
GridwithchildAspectRatiohas rows of that shape; it also hugged its content, and a cell that fills drew almost nothing.
- A definition of several lines side by side, and one that starts with an
ifor aneach, is its lines where the use is: the copies aneachmakes are the cells of aGridaround the use. - A component's parameters:
param @selected=""is a variable parameter,props.selected=…sets it,param items:List=[]is a list of anything andevent onPick:voidpasses nothing. - An overlay a component writes after its tree (
Drawer#basket,Sheet#info stops=[…]) is kept in its document and every page that calls the component has it, soopen basketfrom inside the component works (NotationOptions.componentScreenOverlays). - A Grid of cells written one by one takes its columns at other widths (
Grid cols=4 phone.cols=2). - A
Pageunder another line is the page's scrolling column there, asApp growis an app's region. - Flags as keys:
scroll=false,phone.stretch=true, and=trueor=falseon the alignment words. every 1m,every 1h: timers in minutes and hours.DateTimeInput @duebinds its value. ASegmentedButtonbound to a list variable takes the list as its selection.Grid cols={n} tablet.cols={…}: columns at a width worked out from the state.- The open prompt (
notationPrompt(open: true)) names what the notation already has for a screen-wide shortcut (key mod+k onPress={…}), announcing to a screen reader, the time (now()), a search field, a composer and a one-time code (CodeInput). tool/vocabulary_inventory.dartlists every word the notation accepts by kind, andtool/dictionary_closure.darttests which page words can be written as definitions (docs/design/23-base-and-dictionary.md,docs/design/24-a-design-at-a-width.md).
- A
Navthat writes its own phone menu (show=phone) gets no second menu button. - A
customPaintoranimationline under a node inside aNav, aSectionor another page word is that node's. Pagesin a centring column fill its width; aTableViewthat grows in a column takes the height left.- A box with a
maxwin a centered column is as wide as its place up to that, centered. Stack … clipBehavior=hardEdgeclips what is in it.- A component that fills, called in a row of a fixed width, shares that width.
- An
ifand itselseunder aTableare one cell. - A
Lightboxwith a size on its line is accepted (the size is not read). - Copies that grow, in a row that turns down the page at a width, may say
phone.grow=0orphone.w=fill. drop=… dropTarget.slot=noneanddrag=… draggable.feedbackRotation=0set a field of the record.- A dotted key with a quoted value (
style.fontFamily="monospace") is one key; a field's own word at a dotted key (transformGesture.wheel=zoom) is that word. - A string on a component call fills a text parameter the line does not name; a component's own
sizeparameter keeps its number. - A Table's sort arrow is in the theme's accent.
- A gauge's figure is sized to its shorter side.
- Texts with widths in a row inside a scrolling row keep their widths.
Dotsin a page's Section: the line after it is beside it.- The open prompt's glossary keeps a description that is a whole clause.
resizableon a pane is an issue that names the way to do it (Splitter @wbesidePane w={w}).
- The reference says what
fill,borderandradiusdo on anInput, aSelectand the pickers; that a chip's label color islabelStyle.color=; that a form isform=true; whereSwipeActiongoes; the names a variable cannot take; that anifunder aneachhides what a copy shows, not the copy; and that anExpansionTile's strings are its header.
The notation now writes everything a schema-3 document holds (parity: every corpus document prints back in words), and takes the fixes found by tests 9 and 10, where standalone writers built 6 and then 116 apps and sites from the reference alone. With CodelesslySDK 36.0.0 (the renderer, the tools and Desk, a desktop design system).
- A built-in word wins over a text's own
defineorprimitiveof the same word, with an issue at its line. - A formula whose brackets do not match fails the line (an issue), in every mode; it was kept and read as nothing.
- A components file that cannot be loaded fails the expand (exit 1), open vocabulary or not.
- Overlays per page: an overlay two pages of a site write with one id and draw differently is each page's own
(
nav--board); steps, the outline andprintname it as the page wrote it. - Custom paint order: a node's
painteris drawn over its own fill and border, under its children. - Reflow: a
Tableis left as written (a column says where it is left out); a Row of copies aneachrepeats wraps on a tablet and a phone; an app's window and the writer's own rules are left alone. - Chips chosen from show no check mark unless written (
showCheckmarkdefaults to false). - Sticky tops: a table's header and a
…Head/Mast/Mastheadline stick at 0 (they sat 16 px down). - A key the writer wrote wins over a page word's own; a bare word on an
Iconline is the icon's name (a variable is braced:Icon {glyph}). - Ids may have hyphens and are read as written (34.0.0 read a hyphen as
_). - A Sidebar made narrow at a width is a rail there (
Sidebar w=232 tablet.w=72): an item with an icon shows the icon alone, and the section labels and the brand's text are left out (the rows overflowed). - A horizontal Flex lays its children out as a row's; a text beside a Spacer keeps its own width.
-
Desktop apps in words:
App,Sidebar(withBrand,NavSection,NavItem,Footer),Main,Pane,Splitter,Table,NumberInput,DialogandDraweras a web desktop app draws them; a design system's own definition of one comes first; a site'sprimaryre-accents them. Seedocs/reference/notation/. -
The vocabulary record: every expand records each word written and how it resolved (
notationBuiltInWord,notationBuiltInDefinition); a word with no definition stands in as a placeholder and is said. -
A site's definitions: a
components/<Name>.txtthat begins withdefineorprimitiveis read by every page. -
notationBracketIssues, and a quoted text a line ends inside is said (the parser no longer throws). -
Notation parity (docs/design/22-notation-parity.md): anything a schema-3 document holds is written in the notation's words and
printNotationprints it back in them. Over the corpus (the reference's examples and CodelesslySDK's design systems, examples and fixtures, 1,295 documents) no document prints whole as data (84% did), and 60 of 29,789 node lines keep a{…}tail, each a field no renderer reads in a schema-3 document or a schema-2 spelling the migration rewrites (design 22, section 5). -
Keys by the catalog and dotted paths.
key=valueis, in order, a word of the notation, a prop of the type, a field of its text style, a layout field, a decoration field (where the type is decorated), a field of the node or a behavior:letterSpacing=0.4,squeezable=true,maxWidth=720,strokeSides=topBottom,ignorePointer=true. A nested field is its dotted path (pan.axis=horizontal,style.letterSpacing=0.4,fills[0].color=…,node.tooltip=…); the full path always reads (layout.x=10,props.style.height=1.2) and by it a size is that size exactly (layout.height=108,layout.width=170). A value may be JSON (w={"fill":342},style={…}).key={expression}binds any key;key=nulltakes out a field the line gives;props=null,props={}. A key that is none of these is said with the nearest name, never kept as a silent prop.keys.dartexportsnotationKeyPath,notationKey,notationKeyFor,notationKeyNearest,notationKeyNames,notationTextStyleProp. -
Events and actions. Every trigger of the catalog is
onand its name (onLongPress,onDragEnd,onEnterViewport), its fields in parentheses (onKeyDown(key=Shift+Enter, repeat=true)={…}); the screen's other reactions areon load={…},on backPressed(when={step > 0})={…}lines. Every action of the catalog is its type and its fields by name (animate node=hero preset=fadeIn,runScript script=check onError={toast "Failed"}), withenabled,nonBlocking,when. A quoted string in a field keeps a${…}as written. -
States. A node's states are rules with the state's name as the condition:
hovered.fill=accentDeep pressed.opacity=0.82 focused.border=focusBorder, and on a line inside itbtn.selected.color=primaryText.name=is the node's name; every behavior is written by its fields (inkWell.hoverColor=…,motion.rotate=90,drag=card(item.id) draggable.start=auto). -
Media rules in words.
tablet.direction=vertical tablet.gap=16,max900.size=40,max899.visible={menuOpen},minDesktop.visible=true: any key the line reads at a width (phone,tablet,desktop,min<px>,max<px>, a breakpoint,portrait,landscape, combined);Grid cols=4 tablet.cols=2changes a grid's columns at a width. -
Records under a line. A node's custom paint, animations and transitions are lines under it:
customPaint viewBox=[320,200]with an op a line (circle c=[236,62] radius=28 fill=#FFF4B740,group,repeat,foregroundPainter),animation#enter duration=520with itstrack path=opacity from=0 to=1lines,transition property=opacity duration=200. -
The document line.
document id="checkout" schema=2 scope=page_variables conditions={…}: the document's own id, schema, the scope its state lines are kept in and its conditions.state count:decimal=2,state total:decimal={price*qty},state clamp(v):decimal={…}for a type the value does not say, a formula variable and a function;canvas "Trip" path="/trip" h=844 fill=paper,canvas none;Canvas#about "About"blocks for other canvases;slot titlelines under a node; aListView/GridView/PageViewline with aneachunder it repeats its one child. -
Components. A design system's component document prints as
component StatusPill "…"withparam,event,slotandpreviewlines and its tree. A component a word of the notation shadows isButton "Save" type=Button, with its own events, marks and slots.Pagesprints for a page view of pages. -
printNotation and the coverage tool.
printNotation(document, catalog:)writes any document as notation that reads back (withnotationOptionsFor(document)) to exactly that document: words where they read back, else a{…}tail or adocument {…}line. Overlays print as their heads (Dialog#confirm "Delete file?", opened withopen confirm).tool/notation_coverage.dart <dir>... --components --out <dir>measures a corpus: what is said how, what stays in a tail and why, and the real gaps. -
The notation reference (
docs/reference/notation/,dart run tool/reference/generate.dart --notation): a page per family of the notation with every word and an example that expands and prints back, generated from the catalog;_tails.mdlists what an example still prints as JSON (nothing now).
- Notation: a built-in word wins. A text's
defineorprimitiveof a word the notation already has (a type of the notation or the catalog, a page word, a name the alias table reads as one of those:Card,Rail,Shortcut) is not used, and is an issue at its line saying what the notation has (notationBuiltInWord). Before, one of a core word was ignored with no word, and one of an alias won over the alias (primitive Shortcutmade every shortcut a labelled box). A design system's component may still be replaced by a page's own definition. - Notation: a formula whose brackets do not match is an issue of its line, open vocabulary or not, wherever it
is written (an
eachlist, anifcondition, astatevalue, a{…}value or action, a text's{…}): a)or]that closes nothing (saying where the formula ends and what is not read), one that closes the other kind, and a(or[the line never closes (notationBracketIssues). Before, the formula was kept as written and the engine read nothing from it, with no word: test 10's kanban board wrote one)too many in its list and drew no cards. - Notation: an id may have hyphens (the owner's decision: ids are written as JSON and HTML ids are). An id is
letters, digits and
_, its parts joined by single hyphens (Text#m-title,Dialog#live-image,hero-cta-2), read as written, with no issue, after#, afteropen,scrollandfocus, and as the owner before a state (m-nav.selected.color=…). A variable named after a node (<id>Selected,<id>_<param>, a Lightbox's<id>At) takes the id's hyphens as_.printNotationwrites such ids, so a document with them prints in lines, not whole on thedocument {…}line. (34.0.0 said a hyphen in an id and read it as_.) - Notation: a bare word where an icon's name goes is that name:
Icon download, andicon=inboxon a NavItem, MenuItem or Brand (whose Icon line was refused withUnknown word "inbox" on a Icon), whatever a variable is called, asicon=already was on a Button; an icon chosen by data is braced (test 10: 49 runs, the largest source of first-expand issues). - Notation: a key the writer wrote wins over a page word's own (
Sidebar … h=fill,Table … radius=0 border=rule w=1030): the word's is left out, with no issue. Before, each was "written twice" though written once (test 10: 36 runs). A key written twice by the writer is still said. - Custom paint: a node's
painteris drawn over the node's own fill and border and under its children (the renderer, CodelesslySDK). Before, a filled node hid its painter whole, silently (test 10: 38 runs; 19 showcase documents drew only their fills). AforegroundPainterline may stand under the node besidecustomPaint. - Notation: several
onKeyDown(key=…)on one line are several reactions, with no issue (only the same key twice is said);Avatar … initials="MR"(orinitials={p.ini}) shows those letters, and a one-word name read from the state keeps two letters; a state nameditemread inside aneach(whereitemis the copy) is said;Appbelow a page's header (or in a component) is a region of panes (Rowof Sidebar, Main that scrolls, Pane) where it was "No node type";NavSectionis a section label outside a Sidebar too. - Notation: a call of a component whose slot is
childrentakes the lines under it as its children (what the slot shows); before, they went in a row inslots.childrenand showed nothing (test 10: two single-write sites lost their page bodies). - Notation reflow: a Row of copies an
eachrepeats wraps them on a tablet and a phone (media rules on its list and its item), on a page and in a narrow overlay over it (a dialog); before, the copies were one child to the reflow and overflowed (test 10: 29 runs). A page written for a phone is as written;Row scrollandkeepare left as they are. - Notation, words writers expected (test 10's vocabulary):
Image url="…"(andurl={…},src=) is the picture;Input prefixIcon="search"isicon=;RangeSlider @low end=@highisSlider @low @high; a Grid'scrossAxisCount,crossAxisSpacing,mainAxisSpacing,mainAxisExtentandchildAspectRatioare itscols,gap, a cell's height and its aspect;setThemeMode darkandsetThemeMode {expr};key +andkey mod++;ListView reorder handle(a barereorderon a ListView wastrue, no reorder record: the list did not reorder, silently). Each alias is recorded as one in the vocabulary. - Widgets:
semanticLabeloncheckbox,switch,radioandslider: the name a screen reader says, not shown (textFieldhad it). - Notation parity: a
Canvas#idblock'sblockBack={expr}(andguard={…}) is bound, where the braces were kept as a literal string (test 10, kanban 4);printNotationwrites a canvas's bound props askey={expr}on its line and its own reactions ason …lines under the block, and a design system'sDialogcalled in a canvas with its event (onClose={close}), where each was on thedocument {…}line or a{…}tail. Over the corpus (1,341 documents) the real gaps are 0 (they were 4 node lines and 1 document line, all Desk's dialogs). - Notation:
cond ? actionswith no else is a choice that does nothing when it does not hold (it was "Unknown action"); aneachline takeshandle(each c in cats reorder handle); a paint op's record field takes dotted keys (paragraph … style.color=… style.fontSize=10); a sticky line whose word ends inHead,MastorMasthead(a site's top bar) sticks at 0, as aNavdoes (it was 16 px below the top). - SiteManifest.pageRefs: a manifest's
pagesmay be records ({"id": "home", "file": "home.json"}); a reference page forsite.json(docs/reference/notation/site.md).
Released with codelessly_sdk 35.0.0.
- Notation:
NotationOptions.fromTheme/fromDesignSystemtakenearestColors(default false); withnameda color the notation writes now stays as written unlessnearestColors: true(before,namedalso read it as the theme's nearest color).
- The strict validator (
package:codelessly_api/validate.dart:validateDocument,validateProject,strictEditCheck,Codesand the rest of the library) is gone.applyOpschecks ops withcatalogCheck, as before by default; the reference no longer has the validation codes table, andcatalog.jsonnodiagnostics.
Released with codelessly_sdk 34.0.0.
- Notation: a variable is bound with
@(design note 13, section 3.1).@nameis the variable itself, read and written: bare on a line it is the control's value (Slider @heat min=14 max=24,value=@heatthe same), any other property is named (selected=@pickedon a selectable list,direction=@diron a block,low=@a high=@bon a slider with two thumbs, written bare as@a @b). One bare mark a line, two on a range; a mark on a line that binds nothing, or a second one, is an issue that says what the line binds. A bound variable is declared (astateline, a site's variable, a loop's item, a definition's parameter): one nothing declares is an issue that gives thestateline to add.bind=,bind={…},bindEnd=are not read: each line that writes them is one issue that shows it in the new form (notationBindForm,notationBindRewrite). A block's variable parameter is alwayskey=@name. A definition's signature declares the value a use binds as@value(@value=1with its start) and a further one asname=@(name=@0.5with its start); a use binds them with@x,value=@x,name=@x; a plain parameter a use binds (value=1,Counter @n) is that variable both ways. The prompts, the printer (@nameon a control) and the A2UI front end write the new form. TheRangeSlideralias takes@low @highorlow=@ high=@; its other names for the ends are gone. CodelesslySDK'stool/notation/notation.sh migraterewrites files.notationBindRewriterewrites only what 33 read as a binding (a value in braces on any key butbind=is left: it was shown, one way), lists only the variables it turned into@name, and leaves a binding of a name no state line can declare (notationRefusedState:theme,device…) as written, in itsrefused.
- Notation:
confirm "Delete 2 clips?" "They cannot be restored." ok="Delete" cancel="Keep" danger then {…} else {…}: a detail under the question, the buttons' words, a destructive yes, and what a no runs. - Notation:
key j when={!editing} onPress={…}acts only while its condition holds; akeyline under aDialog#idis that dialog's. Key names are the keyboard's or the plain ones (left,del,pgup); a name no key has is an issue.Button "B" shortcut="mod+b"presses the button. - Notation: a menu opened from a row (
menu=rowMenuunder aneach) reads the pressed row by its loop name; the row's ownonLongPressoronRightClickruns first, wherever it is written. - Notation:
fuzzy(list, q, x=>x.name, 3, "keep")takes how many letters off a word may be and keeps the list's order; letters typed across words match (adamensfinds "Ada Mensah"). - Notation:
Calendar @dayis one day (range: falseon the calendar's props;@a @bis a range), andmarkstakes a list of days or of{date, label}records. - Notation:
guardText="Discard changes?" onDiscard={…}on a guardedDialogorSheetasks before closing;each m in msgs follow growtakes the room over a composer. - Notation: a definition's
primitive Word …declares what no line can express (counted as a stand-in, never as resolved);definitionReadsreports a parameter or an event a definition names and never uses, and a variable it reads that is not its own. - Notation: an alias carries a variant and fixed parameters (
{"to": "Button.primary", "add": "size=large"}) and maps the first string to a parameter ($text); a page's owndefinereplaces a design system's component of that name;description/detail/noteandplaceholder/hintare read for one another where a word has exactly one of them. - Notation: the open prompt's glossary prints each word's signature (
notationGlossaryLines); names alone withsignatures: false.
- Notation: a bare
go namethat names a screen is that screen, whatever variable shares the name (NotationOptions.screens,notationScreen);go {expr}is worked out. - Notation: an id is one word of letters, digits and
_: a hyphen is one issue at the id, which is read with_there and where it is opened. - Notation: a whole-number state becomes a decimal once an action may give it a fraction (
zoom=zoom*1.25) or a slider that writes fractions is bound to it; one bound to a slider between whole numbers stays whole. - Notation:
statelines and overlays written before the first###belong to every screen; a state named after a runtime scope (theme,route,drag…) is an issue; a key written twice on a line is an issue. - Notation:
selectableon a list whose rows take a tap of their own (aTableRow, a card withonTap) chooses the row first; on a line with noeachunder it it is an issue.removableandaction=are read on a block with a slot;disabled={cond}on a block whosedisabledis a list turns the whole block off. - Notation: in a definition, a use's variable reaches the controls in its lines, a loop's item reaches
drag=group(item.id), an event forwards with its arguments, a body that starts withiforeachis put in a Column, and an id written in the lines is the instance's in its actions.
- Notation: an
eachin a wrapping row had no width (aColorPickerdrew nothing);Grid cols={n}read a computed number as 2; a row that holds a reorderHandlewrapped it onto its own line on a phone.
Released with codelessly_sdk 33.1.1.
- Notation: the buttons a
Dialogor aSheetends with are its actions. On a phone they fill its width in equal shares; with room they sit at its right, each no wider than 240. Written as a row of buttons, or as buttons one under another (then they are put in one row). A row that says where its buttons go (between,center) keeps that with room. - Notation: a list beside its detail shows one pane at a time on a phone (design note 13, section 14.4). An
App'sPanebeforeMain, or a column of a fixed width beside one that grows in aRow(aSplitterbetween them goes), whose rows select what the other side shows (a tap under aneachthat sets a value from the row's item:onTap={sel=m.id}) is the list; aPanebefore it whose rows choose what it lists is a level too (folders, messages, a message). The expander adds the state<screen>_pane(starting at the list), media rules that show the level it holds and fill the screen with it, the step to the next level after each selecting tap's own actions (Enter and Space run it too), a back button at the top left of each later level (inMain'sNav, else in a row of its own), the sidebar's drawer button on each pane of an app, Escape and the system back (backPressed, a boundblockBack), and a fade (and the detail's slide) as a pane shows. A tablet keeps the panes side by side where they fit at their least; at the width the page was written for, nothing changes. A tap that only opens a menu, ticks a box or toggles a star does not count, and a pane writtenhide=phoneorshow=…is left as written. - Notation prompt: the page prompt's "Tablets and phones" paragraph says that a list beside its detail shows
one at a time on a phone, with a back button, and that its rows are an
eachwhose tap selects (onTap={sel=m.id}).
Released with codelessly_sdk 33.1.0.
-
A component's word may take a second meaning from a definition (docs/design/20-defined-words.md section 5; the vocabulary loop's Review 5, D25): a definition named
Stepper#stepsgives Cards'Stepper(the number control) the steps indicator the answers also meant by it. The component is the word's first meaning, scored like a definition whose signature is its props and events; a use is read as a named meaning only when it fits it better (a tie is the component). An unnamed definition of a component's word is still not read.DefinedWords(component: …),DefinedWords.meanings(word). -
The open prompt names a design system's words: the glossary (docs/design/19-open-vocabulary.md section 2; the vocabulary loop's Review 6, D29):
notationPrompt(open: true, designSystem: …)adds, after the paragraph asking for definitions, one line with the names of the design system's components and defined words the prompt does not already teach, sorted, with no parameters, and the instruction to use a listed word as one would expect and define only what is in neither list (notationGlossaryLead,notationGlossary). Without a design system there is none;glossary: falseleaves it out. -
A board keeps its columns on a phone (docs/design/13-compact-notation.md section 14; the vocabulary loop's Review 5, D26): a grid of one repeated cell, written on a page or in a defined word's lines, keeps its columns when the cell is a small key from three columns on (a keypad of 3 by 4 was one column on a phone) or, from five, a small cell or a square of at most 64 with no card or component in it (a crossword's 13 columns became two). The node the notation wraps each copy of an
eachin no longer counts against a small cell. AGridtakes up to 24 columns (it was 12: a 13 by 13 crossword had 12). -
The shapes answers gave words we have, read (the vocabulary loop's Review 6, D30):
Text strike=trueis the flag,strike={done}a line through the text while it holds (16 lines in the corpora;underline=the same);Barcode "29034 00718 4421"encodes its string (it was an issue), as bars by default (code128; a QR code issymbology=qrCode), 80 high when no height is given (160 square for a two-dimensional code);value=,code=,format=andtype=are itsdataandsymbology;QRCodeis aBarcodeas a QR code. A design system component's variant that is a value of one of its choices is that value:Banner.warningisBanner tone=warning. -
A defined word used as the first corpus wrote it (Review 5, D25): a use's
bind=xof a variable the page never declared declares it with the word's default (it was left undeclared:SignaturePad bind=signaturedid not validate); a record written as JSON given to a parameter (center={"lat":44.9,"lng":-93.1}) is that record in the body's expressions (it was read as an expression in braces, and did not parse). -
The alias table reaches a defined word: a word's own entries in
parameters,eventsandflags("Timeline": {"events": "items"}) are read as the names its definitions take, before its meaning is chosen; a name one of its meanings takes is its own. Recorded as aliases. -
A definition anywhere in a text holds for the whole text (docs/design/20-defined-words.md section 7; the vocabulary loop's Review 4, D20):
define Word …may come after its uses (models write their definitions after the last screen);parseNotationreads them all before the first line, the overlays after the page included. A//line directly above is its purpose. A page's own definition of a word the design system defines wins on that page, and the use's record says so (VocabularyUse.of:page, over StickyNote.txt).parseNotation(…, definitions: text)takes the definitions of more text (an answer's other screens);readPageDefinitions(text)reads them.NotationStreamreads a definition from where it is written on, and says so when a use came before it. -
The open prompt asks for every invented word to be defined (the vocabulary loop's Review 4, D19):
notationPrompt(open: true)carries a paragraph and three examples (notationDefinePreface) asking the model to define each word it uses that is not taught, after its last screen, in the notation itself. Each example is read, expands with its defaults and validates (a test).define: falsegives the open prompt as the first corpus was written with. 19,804 characters for a page (18,388 without), 10,508 for a card (9,092); the taught prompts are unchanged. -
What self-defining answers wrote, read (Review 4, D21), open or closed:
- an expression where the text or the icon goes is that value:
Icon {playing ? "pause" : "play_arrow"},IconButton {…},Text {…}, as"{…}"would be (a JSON object there is still the tail it was); on a defined word, its first string (Pill {status}); - a Badge's tone worked out from the state:
Badge "Pass" variant={ok ? "success" : "error"}, andBadge.{…}, bind its fill, hairline and ink; - a drag value written as a string or a record,
drag=part("battery"),drag=meal({"rid":r.id}), and a group in quotes,drag="battery"; hide={cond}andshow={cond}arevisible(hidethe opposite);hide=phoneandshow=tabletare still the sizes. Models wrote them 26 times in the two corpora; until nowshow={…}was an error on purpose;- a definition whose body is
if condover its one node is that node shown whilecondholds; state lines before the root are, as before, the word's own state.
- an expression where the text or the icon goes is that value:
-
What got in the definer's way (Review 3, D16; the Sonnet agent that wrote thirty definitions named them):
- a text in a block of a given height (
Column h=200 fill=…,Box w=28 h=28 radius=14with a number in it) keeps that height:{"hug": h}gainsconstraints.minHeight: h(it still grows when the text takes more lines, as its comment always said). The hug value alone is a fallback, so such a block was drawn at its text's height. 131 nodes of 19 example files change this way (in the ten showcase pages: site_docs's three step circles); Row gap=8 wrapover aneachwraps its copies (the list getswrap,wrapSpacing,runSpacing);Word#{tr.id}andWord#lane-{tr.id}on a defined word: an id from data is its fixed part, as on any line;- a path (
end=draft.end) or a variable of the page (bpm=bpm) given to a definition's plain parameter is the value it reads, not the text "draft.end"; every {60000/bpm} onTick={…}: a timer whose interval is worked out (intervalMsa formula);each it in items reorderin a definition, given a list worked out (items={filter(…)}): shown in order, with no variable to write the order to, instead of an issue;- a border's width and colour:
border=2(the theme's line, 2 wide),border="#FF2563EB 2",border=2 borderColor=…,border={on ? 2 : 0}(a width worked out), andborder-width,borderWidth,strokeWidth,border-color,borderColor,strokeColor,stroke.border=2wrote the number as a colour; - an Input's typed text styled:
font,fontFamily,fontSize,weight,fontWeight,letterSpacing,lineHeight; - a choice between actions already took a use's events, given or not (
ok ? onOk : onError): now tested.
- a text in a block of a given height (
-
An
openof an overlay that was never written (Review 3, D17; a third of the first corpus's grammar issues, 256 of 766): with the open vocabulary it opens a quiet placeholder sheet titled with the id (open addRecipe: a Sheet "Add recipe" that says "Not written yet.") and is recorded as a wanted overlay (VocabularyUsekindoverlay, its line the firstopen), not an issue. With the vocabulary closed nothing is made, as before. An id with a hyphen is not an overlay's, soopen add-recipeis still the issue it was. -
The drawer an app's sidebar becomes on a narrow window, and a gallery's viewer, take the screen's id with its hyphens as underscores (
decks_and_mixer_sidebar): a screen id with a hyphen gave an id no overlay can have, and the menu button'sopenwas left out. -
A line read a second time (an overlay's foot, an app sidebar's copy in its drawer) no longer says its issues again.
-
Universal words (docs/design/21-universal-words.md; the vocabulary loop's Review 2, D6 and D7): a parameter, flag or event that means the same on every line, in one table (
notationUniversal,universal.dart: the grammar's own words and the new ones) and read once where a line is read, so core types, a design system's components (where the component has no word of that name) and defined words (without naming it) all have them.coloris a text's or an icon's ink, a control's accent (a toggle's track, a slider's track and thumb, a radio's fill, a choice chip's selected tint), a plain chip's or a field's ink, a filled button's fill (its label's colour when the line gives afill=), and on a container the ink of the texts and icons written in it that set none (nearer wins);size=xs| small|medium|large|xlis a step of the theme's scale on a text (caption, small, body, title), an icon, a Ring, an Avatar, a bar, a slider, a chip and a field (a number on an Input is its text's size);icon=is a chip's avatar and a ListTile's leading icon;disabled(enabled={!…}) on a line with noenabledof its own is itsdisabledbinding (a box:states.disabledwith no pointer and half strength);readonlyon a control with no read-only of its own takes no input (ignorePointer);requiredmarks a field's, a checkbox's or a toggle's label and makes an Input check it is not empty (validator,autovalidateMode: onUnfocus); a tooltip that reads data is the node's own on any line. On the line over aneach:reorder(sortable,reorderable) reorders that list (by a long press, or its Handle withhandle),onReorderhasresultthe new order;selectablewithbind=listandonSelectkeeps a selection (a tap alone, Ctrl or Cmd adds, Shift a range, Space and Enter likewise, Ctrl or Cmd A all, the rows a focus group, each row selected and announced);removablewithonRemove(onDelete) makes a chip an input chip and puts a Remove x at the end of a box. With the open vocabulary each use is recorded (kinduniversal,ofits kind); a stand-in's words it honours are recorded so (D6), what it leaves out stays in its record. -
Input's words (docs/design/21 section 7, D8):
clearable(a x that clears it),maxlength/maxChars(maxLength, the field taller for its counter),capsandcaps=words|sentences,autogrow,rows=(lines=),centerandright,value=besidebind=,prefix=andsuffix=(always shown),onEnter(onSubmit),onSaved(onBlur),onKeyDown(a key in the field,keyread asresult.key);fuzzyon an Input is a recorded no-op with an issue that says fuzzy matching belongs to the filtered list.Calendar onSelectisonChange. -
A bare number where the text goes (D9):
Badge 3,Text 2026,CountUp 39(a stand-in), a component's first text parameter (or its numericvalue), before any key=value on the line; on a defined word the next string of its signature, else its parametervalue(the number itself in the body's expressions), which closes note 20's grammar gap. A number after a key, and a bare word naming a value (Text plan.name), are what they were. -
Words defined in the notation itself (docs/design/20-defined-words.md): a word's signature (its strings, parameters with defaults, flags,
bind=name, events) and the lines it stands for, written in the notation's own grammar, one file per word (StickyNote.txt) ordefine Word …in a page. A use is written out as those lines before it is read (a macro): the use's values where the body reads them by name in braces, its words of every line (w,grow,visible,onTap…) on the body's first line, its lines where the body has...(or...Frontfor the lines under aFrontline;... each reorderaddsreorderto aneachin the slot), the body's state, loop items and ids made the use's own, its events where the body names them (onPick(c): withresultasc). One word may have several meanings (Timeline#tracks,Timeline.vertical#route): a use is read with the one that fits what it gives. A word that uses itself is refused. A core type, a catalog type, a page word or a component is never a definition's. Open or closed, a defined word is a word we have; each use is recorded (VocabularyUsekinddefinition,tothe meaning,nodeits root id); what it gives that the definition does not take is recorded with the vocabulary open, an issue without. A definition's own errors are said against its file and line.NotationOptions.define(texts),NotationVocabulary.define(texts)and.definitions;readDefinitions,checkDefinitions(each definition expanded with its defaults, with an optional document validator),definitionLines(the signatures, for a taught prompt),NotationDefinition,DefinedWords.
-
A stand-in with nothing to draw shows what is missing: with the open vocabulary, an unknown word with no text, no lines under it and no fill or border of its own is a quiet dashed box with its word (and its first string value), at least 40 high or as big as its
wandhsay, in the theme's line and caption colours. A page with a word we lack reads as unfinished, not broken. Nothing else changes; with the vocabulary closed nothing stands in.
Released with codelessly_sdk 33.0.0.
-
The compact notation has a new grammar, and reads only it (docs/design/17-notation-grammar-audit.md). Everything after a node's text is
key=value; a value worked out from the state is in braces, as inside a text; a control's variable isbind=name; what a node does is an event with its actions in braces, and there is no arrow.Before (to 32.x) Now Column gap:12 pad:16Column gap=12 pad=16Input "Email" =emailInput "Email" bind=emailselected:=tab=="a",enabled:count > 0selected={tab=="a"},enabled={count > 0}Button "Save" -> saved=true; toast "Saved"Button "Save" onTap={saved=true; toast "Saved"}Slider =volume -> emit volume resultSlider bind=volume onChange={emit volume result}SiteNav … -> go lower(result)withonCta: go signupon a line under itSiteNav … onNavigate={go {lower(result)}} onCta={go signup}swipe:left -> …,drop:todo -> …,every 1s -> …onSwipeLeft={…},drop=todo onDrop={…},every 1s onTick={…}show:menuOpenvisible={menuOpen}(show=phoneis a size)Heading "Why" #why,id:whyHeading "Why" id=whyIt is a hard break: the old spellings are not read, and each is an error on its line that says what to write (
A value is written with =, not a colon: gap=12.,There is no arrow. What a node does is an event with its actions in braces: onTap={…}). Also no longer read: an expression with no braces after a key or where the text goes, a declared variable written bare after a key (said, withkey={name}), a list holding expressions with no braces, a block's enumerated value as a bare word,tap:/press:/click:/change:as events, an event's actions in quotes,valueforresult,List =rows. Still read, though not taught:let, a barename = valueline,for x in,each list,else,+=,++,.add(),if (c) {…}in actions,$name, single quotes,sticky=true,onPressed/onClick/onChangedforonTap/onChange,onTapon a block for its first event.To migrate a file:
tool/notation/notation.sh migrate <file.txt> --design-system <folder>in CodelesslySDK (a one-off tool outside this package; docs/design/18-notation-grammar-migration.md is the note to hand to whoever has files). Every notation file of the SDK and every page of the twenty sites expands, rewritten, to the document it expanded to before. -
New on a plain node:
onHover,onFocus,onBlur,onSubmit(the engine'scursorEnter,focusGained,focusLost,submitted); anon…it does not have is an error that lists the events.id=nameon a line is an anchor. A plain node's unknownon…used to run on its tap or change. -
notationPromptteaches the new grammar: 8,979 characters for a card (8,913 before), 17,736 for a page (17,644). A design system's component line lists its events by name (Stepper "label" bind=value min max onChanged : …). The printer writesgap=12, and the A2UI front end the new grammar.
-
The notation: a choice between actions. Inside an event,
cond ? action(s) : action(s)is anifaction (onTap={dirty ? open leave : go members},onChanged={…; pendingRemove=="" ? close : open removeConfirm}); each branch is one action or a braced list, either may be empty (done ? close :), and a branch may choose again.if (c) { … } else { … }in actions, read before as assignments guarded one by one (its other actions ran unguarded), is now the sameifaction. A value chosen (step = valid ? 3 : 2) is still a formula. The card prompt teaches it in one clause in place of "an action is never a condition". -
The notation: binding to a field.
bind=draft.titleon a control writes the field of the record variable (draft = with(draft,"title",result)); under aneach,bind=s.donewrites the element back also when its list is a field of the element around it (each s in e.sets), and when the list is worked out (each d in filter(devices, …)) and its records have anid. A design system's block (ToggleRow, NumberInput, TextArea…) takes the same: its variable parameter is given the field's path (draft.title,"rows[" + index + "].done"), where it saidA NumberInput keeps its value in a variable: write bind=name.What cannot be written (a list worked out without ids, a record that is not declared) says what to write. The same holds for an action that sets a field where it stands (d.pos=0under an each over a list worked out,draft.title=""), and a control reads and writesbind=colAll[r](an entry of a list or a map variable) andbind=find(clips,c=>c.id==sel).name(a field of the record a find picks). -
The notation: lines under a block that takes none. Under a design system's block with a slot and no children (
ListRow's trailing,SectionHeader,PaneToolbar,EmptyState's actions) the indented lines go in the slot, side by side; the component's prompt line says(lines: actions). Under one with neither, the line is an issue that says so and is drawn after it (the renderer reportedchildren_not_allowedand the expander nothing). A line indented two levels past the one before it inside an overlay (a page's Card written after the overlays) says it went into that overlay. -
The notation: ids. The drawer an
Appmakes of its sidebar on a tablet or phone is<screen>_sidebar(was<screen>Menu, which tookMenu#albumMenufrom the author on the album page,Dialog#deckMenuon deck…). An id given twice names the line that has it (The id "save" is used twice: line 8 has it too.); in the two branches of anif/elseit says why a document cannot hold both and what to write; an overlay with the page's own id says to give it one of its own. An id written from the data (Row#row-{row.id}) is its fixed part (row): a node has one id however many copies aneachmakes of it. -
A component's own variables reserve none of a site's names.
validateProjectreported a project variable (site.json) named like a variable inside a design system's definition (selectedin Cards' CommandPalette,queryin its Combobox) asduplicate_variable, in sites that never used the component. A definition's variables are its instance's; only a page's are checked against the project's. -
The notation: lines that were accepted and did nothing.
project cart=[]on a page expanded alone declarescarton the page (it declared nothing, and every read of it failed at render); beside site.json it is the site's as before, and a name the site's variables lack is said.go result,go tab,go item.slug(a name the state has) navigate to the page the value holds, asgo {result}(Tabs … onChanged={go result}went to a page called "result"). With an open vocabulary, anopenof no overlay of the page names the ones it has.clip.lengthof a record with alengthfield is the field, not the record's size.state clips=[…] saved=true(orpersist=true) is the saved flag, where it was read into the value as text. -
The notation infers a variable's kind from the state declared. A variable an action makes takes the kind of what it reads (
x=c.startunder an each over clips whosestartis a number is a decimal,completed=c.donea list), where it was text and the renderer saidwrong_type; one that cannot be known takes the kind of a control bound to it later (aNumberInput, aSlider). A design system's parameter that is a list of texts given numbers (ChoiceChips options=[1,2,3],Tree depths=[0,1]) takes them as texts. -
A Grid whose columns mean something keeps them on a tablet and a phone.
Grid cols=7(a month, a streak, a timetable), a grid of five or more small cells (at most three nodes, no card or component), and a grid writtenkeep(Grid cols=4 keep) keep their columns and shrink their cells, where a phone made two columns (a month became a 15-row list). Other grids wrap as before. -
A bar pinned to the foot of an app window.
FooterasMain's last line (or inApp, orRow sticky bottom) is a bar at the bottom ofMainthat stays in view at every width while what is above it scrolls (a now-playing bar, a chat composer, a basket, sheet tabs); before, a Card written last inMainscrolled away. The alias table readsStickyBar,StickyFooter,BottomBar,FooterBarandBottomDockas it. The page prompt teaches it in one line, and that a Grid of 7 columns or writtenkeepkeeps them. -
The notation:
selected,size,focusandcopy.selected={…}on a line whose type has no selected value (aRowof a list, anIconButton, aButton) is the node's selected state (bind.selected); a row, column or box is drawn in the theme's selected fill while it holds.size=small|medium|largeon anIconButtonis its icon's size (a Button's was read already). Actionsfocus search(the caret in that field),blur, andcopy link/copy "{link}"(to the clipboard, with a toast); the page prompt names them. -
An open vocabulary for the notation (docs/design/19-open-vocabulary.md): the prompt teaches the grammar and a small core, the model writes any word it expects, and the parser records the ones we do not have.
NotationOptions.openVocabulary(false by default: nothing changes without it). With it, an unknown type is not an error: it stands in as a column of its strings and of the lines under it, with its id, its layout words,visible, and what a pointer does to it; at the margin after the page, with an id, it stands in as a Dialog. An unknown parameter, flag, event, action verb or variant, and a value of another kind than a parameter takes, are left out of the document. A component called without something it needs is given an empty value; lines under a word that takes none are drawn after it; anopenof nothing over the page and ascrollto no line of it are left out, with an issue. The grammar is not open: what does not follow it is still an issue.NotationResult.vocabulary(andNotationStream.vocabulary): aVocabularyUsefor each such word, with its kind (type,parameter,flag,event,verb,variant,missing,children,alias), the word, the type it is on, its value as written, the whole line, line and column, the words it is under, and for a type its strings, parameters, flags, events and the first words of the lines under it.- Aliases:
NotationOptions.vocabulary, aNotationVocabulary(fromJson,toJson,merge;NotationVocabulary.coreby default,.nonefor none). A name for a word we have is read as that word, with the vocabulary open or closed, and each use is recorded. A type (with its own names for the target's parameters, words to add, and the keys it requires), a parameter for one type or all (another key, the key negated, or a string of the line), a flag, an event, a verb, and three lines of another shape. Built in, from the first corpus:Shortcut "ctrl+k" onPress={…}andshortcut key=t …(thekeyline),state x=1 persist(saved),disabled={x}anddisabled(enabled),ListTile … subtitle="…"(its second string),computed x={…},ConfirmDialog#id "…" onConfirm={…},Highlight/HighlightTextwithmatch=/query=(Text … mark=),MiniCalendar/CalendarMonth/MonthGrid(Calendar),RangeSlider low=a high=b(Slider bind=a bindEnd=b). A word the notation already has is never an alias. notationPrompt(open: true): the open preface, the grammar and the core; no component list, no behaviour words, no JSON escape. 18,151 characters for a page 1280 wide, where the taught page prompt is 20,651 (73,270 with Cards' components). The taught prompts are unchanged (the card prompt is 8,979 characters).NotationOptions.open({openVocabulary, vocabulary})gives the same options with these two set.
-
key escape when editing onPress={…}: a shortcut that runs only while a condition holds (the trigger'swhen), asevery 1s when runningdoes. -
Progress {done/total}(alsoRing,Gauge,Slider): an expression where the bare number goes is the value it follows, asbind={…}is. It was a "not valid JSON" error. -
An overlay written inside the page (
Dialog#editindented under a pane; also Sheet, Drawer, Menu, Popover, Lightbox) is over the page, its lines the ones under it, and the page goes on after it. It was an unknown type. With a design system that has its own Dialog, aDialog#idin a line is still that component unless anopennames its id. -
Nineteen behaviours a page can now write (folded from the
dsl5/*branches, each in the 33.0.0 grammar; the page prompt teaches them, the card prompt is unchanged at 8,979 characters, the page prompt is 20,580):confirm "Remove it?" then {rows=[]; close}in an event's actions: the document'sconfirm, its actions run only on a yes.state draft="" saveddeclares the variable withpersist;project cart=[] savedchecks that site.json's variable says"persist": trueand has the same type.CodeInput "Code" bind=code length=6 digits: a text field's newotpLengthandotpDigitsOnly(a one-time code: one field drawn as boxes).Slider bind=low bindEnd=high min=0 max=100: a slider's newrangeEnd, a second thumb; achangedgivesresult.lowandresult.high.each line in lines follow h=180: a list that scrolls in that height, opens at its end and follows what is added (stickToEnd). An each's trailing words (stagger=,follow,h=,reorder) are read in any order.Text "{r.title}" mark={q}binds the text's runs tomatchRuns(text, q); the formula table gainsfuzzy,fuzzyScore,matchRanges,matchRuns,matchReason(each r in fuzzy(rows,q,x=>x.title)).- A new action,
announce(onTap={announce "{n} results"}: said to a screen reader, nothing shown), and a text'slive(Text "{n} results" live). Dialog#edit "Edit" guard={name!=""}binds the overlay canvas'sblockBack;Sheet#filters stops=[0.5,0.9]writesopenModal's newsnapHeights.- A new control,
splitter(Splitter bind=paneW min=200 max=640, withstep,collapseAt,orientation,label): a divider between two panes, its value the first pane's size (Column w={paneW}). - A slider's
trackShape: starsandreadOnly: a rating (Cards' block:Rating "Your rating" bind=score half,Rating "Score" score=4.5 readOnly). - The page prompt says to name an icon-only button with
tooltip="Clear filters". openModalgainshoverCard,hoverDelayMsandpopoverArrow:Link "About Mara" preview=bioopens that Popover as a hover card,Popover#bio arrowpoints at its opener.key mod+k onPress={open search}on a line of its own is a canvaskeyDownreaction; a text's newshortcut(Text "Search" shortcut="mod+k") shows the combination as the platform writes it.each stop in trip reorder(andreorder=groupbetween lists) withHandle, a row's grip: the list'sreorderby handle and keyboard, applied to its variable, its handles onefocusGroup.SwipeAction "Book" side=end when={!row.full} onTap={picked=result.item.name}under an each: the list'sswipeActionsand aswipeActionreaction (removestakes the row out of its variable).device.hoveranddevice.pointerare read-only values (if !device.hover); a variable nameddeviceis refused.- A text field's
min,max,step(Input "Qty" bind=qty type=number min=1 max=12 step=1) andsemanticLabel; a click trigger'srepeat,holdMs,intervalMsalso mean a click repeated while held. - A new control,
calendar(Calendar bind=arrival bindEnd=departure disabledDates=["2026-11-24"] marks={"2026-11-20":"£225"}): a month in the page with a range,firstDate,lastDate,dayPrices,label; achangedgives{start, end}. tableViewgainssortable,sortColumn,sortAscendingand asorttrigger; the notation'sDataTable rows={orders} columns=[{"key":"name","label":"Customer"}] bind=row onSort={…} onRowTap={…}is that table with the theme's texts, the chosen row's place inrow.
-
The keyboard:
focusable(default true; false takes a node with aclickreaction out of the focus order),focusGroup({axis, wrap, typeAhead}ortrue: what is focusable inside the node is one Tab stop the arrow keys move through) and a canvas'ssemanticLabel(its name for assistive technology when it opens as an overlay). The interaction and navigation references say what the keyboard does on press targets, groups and overlays. -
Right to left: padding and margin written
{"start", "top", "end", "bottom"}are Flutter'sEdgeInsetsDirectional(EdgeInsets.fromSTEB,directional,resolve);strokeSidesgainsstart,end,noStart,noEnd(BorderDirectional). The layout reference has an RTL section (whattextDirectionmirrors). -
Validation:
widthFactorin a row (heightFactorin a column) is reported as ignored (layout_field_ignored); an expression written into an animation field is reported (loose_value) with the binding to write instead. -
Docs: a binding of a field an active interaction state patches yields to the patch.
-
dragEdgeScroll(scrolling containers, lists, grids; default true): whether the view scrolls while a drag and drop is held near its edges. Off for a strip that should stay put under a drag: sprint_kanban's phone column tabs, where the strip scrolled the tab out from under the card it had just switched columns for. -
DropTarget.slotWhenRefusedis back in schema 3 (default false): the list opens its slot for a dragacceptIfrefuses too, as Flutter'sDragTargethands its builder the rejected candidates (a kanban column at its WIP limit shows where the card would land, styled as blocked). The migration writes it out where schema 2 left it at its default (true) with anacceptIfand a list slot, so such a document renders as before instead of reporting a behavior change (sprint_kanban's columns relied on it). -
Notation, the page words: the frames of a desktop page, written out as plain lines before they are read. A website is
PagewithNav,Section(a full-width band, its content in a centered column;narrow,fill:,center) andFooter. An app window isAppwithSidebar,MainandPane w=320, each as tall as the window and scrolling by itself. AlsoNavItem "Orders" icon="inbox" badge="12" selected={…} onTap={…},Link "Docs",Heading "…" level=1. Inside a card the same words are a plain row or column. -
Notation:
border-bottom=#…(-top,-left,-right) is a rule on one side;stickykeeps a node in view while the page scrolls;Text … italic. -
NotationOptions.height,contentWidth,selectedFill,line: the window an app is drawn in, the widest a section's content gets (a theme'ssizes.content), and the looks of a selectedNavItemand a rule. -
Notation, a theme's page tier: on a wide canvas (a theme's
sizes.wideand up) a name ending inWidetakes the place of the name before it (textStyles.strongWideisText.strong,radii.cardWidea card's corner,spacing.cardWideits padding,shadows.cardWide,sizes.ctaWide). One theme then serves a chat card and a page with nothing switched: a card is written at its own width and keeps the card's looks. -
Notation: a button's
size:(xs,compact,small,medium,large) is its height; a theme'ssizes.controlis the height of a button, a field and a select that write none.Section tint(a band on the theme'scolors.band) andSection compact;IconTile "sync";Brand "Harbor" icon="anchor". A selectedNavItemhas its label and icon in the accent. A website page is drawn oncolors.pageFill, an app's sidebar and top bar oncolors.card.Headingin an app is the page's title (level=1), a panel's (level=3). -
NotationOptions:narrowWidth,sidebarWidth,sectionPad,gutter,band,siteFill,paneFill,iconTile,controlHeight(a theme'ssizes.narrow,sizes.sidebar,spacing.section,spacing.gutter,colors.band,pageFill,card,iconTile,sizes.control). -
notationPromptteaches the page words whenoptions.widthisnotationPageWidth(700) or more, and adds the design system's "Pages in brief" (a section of its patterns) when it has one. -
Notation, a page at other widths: a page written once for a desktop lays itself out on a tablet and a phone. From 700 wide on the expander adds media rules below 1024 and below 700 (
PageReflow,reflow.dart): aGrid's rows wrap, aRowof blocks wraps, any other row wraps before it overflows, a table's row keeps the columns it has room for, anAppshows its main pane, aNavhides its links, sections and headlines are smaller. The page at the width it was written for is unchanged.NotationOptions.reflow(default true) turns it off. Design note 13, section 14. -
Notation:
hide=phone,hide=tablet,show=phone,show=tabletsay where a line shows; they hold on a line under anif, and a line that carries one is left out of the reflow's own hiding. -
Notation, overlays: a dialog, a sheet, a drawer, a popup menu, a popover and a lightbox are written after the page (
Dialog#id,Sheet#id,Drawer#id,Menu#id,Popover#id,Lightbox#id) and opened withonTap={open <id>}, each a canvas of its own with the right presentation; their lines read and set the page's values.menu=<id>opens a menu on a right click or a long press. AnApp'sSidebaropens as a drawer on a phone from a button added toMain's top bar. -
Notation: a website's
Navbuilds its own phone menu from its links (each as written;menu=falsekeeps one out; aNavwith ashow=phoneline keeps its own);Nav stickyandSiteNav … stickystay at the very top (sticky=0), aNavon the page's surface. -
Notation:
scroll <id>moves the page to a line, named by its id (Section#pricing) or by an anchor (id=pricingon it);Link "Pricing" href="#pricing"does the same.gotakes a destination worked out (go {replace(lower(result)," ","_")}); a page id may have hyphens. -
Notation, a viewer:
Lightbox#zoom "{photo}" "Caption"shows a picture large over the page: a pinch and the wheel zoom about the point, a double tap goes to 2x where it was tapped and back, a drag pans while zoomed, and it closes by its button, Escape, a tap on the scrim and a drag down.Lightbox#shots photos={photos} bind=atis a gallery: a page per picture opened at the one tapped, turned by a swipe, its arrows and the arrow keys, with a count, the caption and a strip of thumbnails;ratio=(or a record'sratio) gives the picture's box its proportions. On a page, a design system's gallery that takesviewer="overlay"(Cards' PhotoGallery) opens its photos in a viewer the expander writes once. The reference has the render command's--double-tap,--wheeland--pinchsteps. -
Notation, tabs:
Tabs bind=tab tabs=[…]is the design system's own Tabs where it has one; the prompt keeps aSegmentedButtonto two to four short options, never a page's tabs. -
Notation:
Input "Search" icon="search"puts the icon inside the field, before the text (it was written as a prop the field does not have, and lost). -
Notation, a site's variables:
NotationOptions.projectVariables(a site manifest'svariables) andproject name=valueon a page: read and set by name, with no copy declared on the screen to hide them. -
Notation:
Section bleedruns its content from edge to edge; aDonutwritten withlabelsdraws them as a legend beside it, under it where there is no room (legend=false: the chart alone; a page that writes the labels itself keeps its own); a date or time field's string is its label, and on a page the field is as tall as the fields beside it;NotationOptions.accentText(a theme'saccentTextoraccentDeep) is a link's ink in running text. -
validateSiteManifest: a key ofsite.jsonthat nothing reads is asite_key_ignoredwarning; a theme key written beside"theme"("primary","colors","dark"…) says to write it inside"theme"(it was ignored without a word).
- Notation: a root written
h=fill(andApp) gives the canvas the window's height, where it was as tall as its content.Row between centerkeeps its ends apart and levels its children (it was read as centered). A row that spreads its children is as wide as its place, in a centered column too. An icon keeps its size in a column. ASpacer growin a column takes the height left. A design system's block in a row shares the row's width where it filled it; aradius,fillorborderwritten on a block is left out.
- Notation:
Input "Email" type=email, which the prompt teaches, wrote a keyboard the document does not have (email; it isemailAddress). Also read:tel,numeric,decimal,search,date,time,address. - Notation:
state shown={filter(rows,r=>r.open)}kept the braces in the formula, so every value that readshownfailed to parse. A formula in braces is that formula (a map,{"a": 1}, is still a map). - Notation: a color in a formula written as it is after a key (
fill={late ? #FFFECACA : #FFFFFFFF}) is the text it is; the formula did not parse. - Notation:
grow=truewrotetruewhere the document takes a number; it isgrow(grow=false: nothing). - Notation:
onTap={open <id>}wrote its canvas under a key the document does not read (modal; it isto). - Notation: a short loop name no longer rewrites a layout key of the same letter (
each h in homeswithh=120); an unbound boolean state of a block gets a variable of its own. - Notation: a donut's first slice and a chart's first series were written as a theme name where a value is
read, and did not draw; a donut given a height is as wide as it is tall. On a page: cards side by side in a
row are equally tall; a field in a bar (or labelled "Search…") has its label as its hint; a
Badgewith a width sits in a cell of that width; aTextwith a rule, a fill or a corner is a box around the text;id=x,sticky=true top=24and an Avatar'ssrc:are read as meant. - Notation: a see-through
fill:on aCardsits over the card's own color (alone it let the card's shadow show through);'single-quoted'text in a value ends at its closing quote;Sparkline values={row.trend}draws from a record's list; acolor:on a checkbox, switch or radio is its color when on; a text in a box of a fixed height makes the box grow instead of overflowing. - Notation: the braces of a code sample shown as text (
import { Beacon } from …) are text, not a value read. - A site manifest's
variablesis read in the forms it is written: the list of records, or an object by name ({"cart": [], "plan": "pro", "draft": {"value": "", "persist": true}}: a name and its value, or a record without its name;Variable.declarationsFromJson). A variable that names notype, in a manifest or a document, has its value's (VariableType.of:[]a list,3an integer,truea boolean); it was text, so a list started empty and numbers were joined as text, with no diagnostic.validateSiteVariablesreports each record that cannot be read (invalid_variable, with the shape to write). The notation's page prompt and the reference's "The site manifest" show the shape. - The notation: a variable declared with a whole number (
state amount=0) and bound to a component's number parameter (NumberInput bind=amount step=0.01) is declareddecimal, notinteger: an integer variable rounds what is set, so typed cents and a 0.01 step were lost (25.50 was saved as 26, the arrows did nothing). A site's variable (site.json) keeps the type it is declared with there. - A site's theme over a design system's tokens (
DesignSystem.themeUnder, the newThemeTokens.withSiteTheme): what the design system makes from its accent follows the site's. A site that gives its ownprimary(orcolors.accentwhere the accent is the primary) gets every color that is the design system's primary at some opacity (a selected row's tint, the focus ring, tinted borders) at that opacity of its own, theinfocolor and its tints, and each shade named after the accent (accentDeep,accentBright) in its hue; in dark, with nodark.primaryof its own, a primary made from its light one (it stayed the design system's blue) and the same for the dark colors. A site'sfontFamilyre-families the design system's text styles of its default family. A color or style the site names itself stays the site's.
Released with codelessly_sdk 32.0.0. Stored documents and the JSON format are unchanged; the one breaking change
is in how the compact notation reads Column center.
- Notation:
centerandmiddleon aColumnswapped.centernow centers children side to side;middlegathers them at the column's middle. Notation that wroteColumn centerexpands differently.
- Notation, meters and charts:
Gauge/Dial(limit:,unit:),Ring,Sparkline,LineChart labels:[…] series:[…],AreaChart,Donut. - Notation, motion:
animate:<word>(fade, slide-up, slide-left, scale, pop, bounce, shake, pulse, spin, shimmer) withduration:,delay:,stagger:;swipe:left -> …. - Notation, layout: several top-level lines are a page's sections, stacked; a
Stackplaced withleft,right,top,bottom, or centered withcenter middle;maxw:;grow:=value. - Notation, parts and props:
Avatar;Input … password/multiline; a slider'sstep:;Text … center/strike; anIconButton'scolor:andsize:;gradient:[…]; aneverywith its actions on the next line. TextProps.markdown: a text shown as Markdown (bold, italic, code, links, @mentions, lists) with the markers taken out. Same keys asTextFieldProps.markdown.- Two schema 2 → 3 migration steps for projects made before the v2 SDK:
text.markdownmoves a text's Markdown look toprops.markdown;trigger.fieldResultrewrites a text field reaction'sresult.value,result.word,result.cursor,result.selectionStartandresult.selectionEndtofield.*. - Theme names the notation uses when present:
sizes.widewith atitleWidetext style (wide page titles fromNotationOptions.fromTheme(width:)),sizes.ring, text stylesgaugeValueandgaugeUnit,colors.pageFill. A theme without them is unchanged.
- Notation is more forgiving: props guessed in a JSON tail are read as the notation's own keys, or reported at their line; single quotes hold spaces in an expression; fixed text widths in a row become shares when they do not fit.
- A required component parameter set to its default value is kept.
Propsdropped it, and the call then reportedmissing_prop.
Released with codelessly_sdk 31.0.0. Nothing a document written for 30.1.0 uses has changed.
-
The compact notation (
package:codelessly_api/notation.dart):Pages =page(swiped pages bound both ways,peek),Dots =page count:n,Row scrollscrolls sideways, sideways scrollers fade at their edge, and a value that follows state is read as a model writes it: the name bare (choice:pick), in braces, or the expression with no mark (enabled:!voted); a list holding expressions is a formula;true,falseandnullafter:=are values. On a block's line, a bare word one enumerated parameter has,key=valueand a further string are read as the parameter they can only mean.NotationOptions.fromTheme(named: true)writes looks as the theme's names. -
notationPromptcarries a design system's composition brief (its PATTERNS.md "In brief"). -
More of what models write is read (each from a recorded answer, each with a test): a handler as a key (
onPressed:{…},tap:"…"), statements after->as in code (n += 1,row.done = !row.done,rows.add(x),rows.remove(row),if (c) { a = 1 }),let name = expressionfor a worked-out value,for x in list,else,and/or/not, calls on a value (total.toFixed(2),rows.length); a condition in braces with spaces and quotes;key:={…}; a text inside a list or inside a formula that reads a value (items:["Lemons, {2 * n}"]); a list written over several lines; a value in braces that holds its own braces; a property written after the actions; a code fence around the answer; a parameter named like a handler (change:1.84);formatTime(seconds)asduration. An action that sets a worked-out value is dropped (the value follows the state by itself) instead of corrupting the line. -
Wanted "Name" "what it shows": a part no component fits, built from plain types under the line and shown as written; the request is inNotationResult.wantedandNotationStream.wanted(WantedBlock).notationPrompt(wanted: true)teaches it;notationPrompt(natural: true)is a variant that teaches values and actions in the forms above (not the default: it did not measure better). -
duration(seconds)andconcat(a, b)are in the notation's list of functions. -
edgeFadeon scrolling containers and page views. -
Validation: a project component replaces its design system's of the same type (it was reported as a duplicate).
-
The compact notation, first version (
docs/design/13-compact-notation.md):parseNotationinlib/src/core/notation/notation.dart(internal, not exported yet) expands one node per line, nested by indentation, to an ordinary document: short type names (Input,Toggle,Button.ghost,Card,Text.title), a main string,key:valueprops,=nametwo-way bindings that declare their variable,->actions,state,if,{name}in text and a{…}JSON tail. What it cannot read is reported by line. -
labeloncheckbox,radioandswitch: text beside the control (SSUI's; Flutter has the*ListTilewidgets for it). Tapping it toggles and it names the control to a screen reader. -
An expression written where a plain value goes is bound, not rejected.
"radius": "${theme.radii.panel}","visible": "${step > 0}", a non-text prop:applyOpsmoves it into the node'sbindunder the field's path and reportsexpression_bound(a note, with the binding written). A path already bound keeps its binding; text props read expressions as written and are left alone.strictEditCheckpassesValidateOptions.levelthrough. -
Levels of the vocabulary (
docs/design/12-agent-first-flutter.md).lib/src/core/levels.dart(internal, not exported) gives every node type, action, data source, behavior and trigger a level: core, widgets, state, design, full, features.catalogAtLevelcuts a catalog to a level,levelOfandlevelUsesread a document's, andValidateOptions.levelreports anything above the level given (above_level). -
Date and time pickers (Milestone 3, workstream G): the
datePicker,timePickeranddateTimeInputdocs describe the SDK's own pickers (SSUI's field, a calendar or hour/minute columns in a popover or bottom sheet; an empty value shows its hint), no longer Material's dialogs;docs/design/11-no-widgets.mdmarks workstream G built. -
Design 11: the text field as built (WS-A, section 3.2): field frame, editor and what is left (handles, toolbar).
-
Milestone 3, kit follow-up and workstreams C and I: a control (
WidgetSpec.hugs: buttons, chips,badge,circularProgressIndicator,activityIndicator) with nolayout.width/heighthugs its content instead of being 0 × 0 (zero_sizeno longer reported for it); buttons takeloading(SSUI'sisLoading);TriggerType.deleted(an input chip's delete icon, Flutter'sonDeleted); the chip, badge and spinner docs say what their default (SSUI) look is. -
Milestone 3 design:
docs/design/11-no-widgets.md(the renderer as render objects with noMaterialApp,Navigator,Overlayor widget per control; the control kit; SSUI as the default look; the split of the remaining controls into parallel workstreams). -
Theme roles:
ThemeTokens.resolvedRoles()gives the roles (primary,onPrimary,surface,onSurface,error,success,warning) as colors, a role that names a theme color ("primary": "forest") resolved through any chain of names; such a role never reached controls before (they drew black or white). A role written insidecolorsis a second spelling and is reported,theme_role_in_colors(warning), with the key to move.ThemeTokens.roleNames. The STARTER's theme example declaresprimaryandonPrimaryby color name. -
Buttons (
filledButton,outlinedButton,textButton,elevatedButton,iconButton,floatingActionButton) takeautofocus(Flutter's), and drawWidgetState.selectedthemselves: a boundselectedon a button no longer reportsstate_no_effect.WidgetSpec.states(catalog JSONstates) lists the states a type's own look draws. Their docs say what the default (SSUI) button is.
What ten sites built as data (brief 3) ran into.
- Validation: a list's pagination controller (
props.pagination.name) is a name its page may read (${coastPages.page < coastPages.pageCount}wasunknown_name). gridView.fillGaps: CSSgrid-auto-flow: dense, automatically placed items filling the holes earlier spans left.navigate.tomay be an expression (${item.to}): documented on the action; the SDK now evaluates it.fit_not_allowedin a wrapping row gives the fix (basis, with an example);decoration_ignoredon a text says how to make a filled, rounded label (a row around it) or a highlight (style.backgroundColor).- Reference: a page gutter and max-width recipe that keeps every section on one left edge at 390, 834 and 1440, and
hero sizing (layout); submitting a form with no backend and simulated loading and error states (forms); a
tableViewwith bound data (lists); updating one list line at itsindexand UTC offsets instead of IANA time zones (state); counting a number up, and running severalanimateactions together (animation); explicit grid placement under a filter,scrollTo's offset under a fixed header and scrolling to a heading on another page (layout); declaring a variable font once (theme);step_skippedandpage_not_written(render).
Valid but blank, explained. Of 34 recorded SSUI generations, several final frames showed an empty card or a card missing its content. Causes in this package, and what a model is now told:
-
A
varsop with one formula that does not parse (or reads an unknown name) is no longer rejected whole: its other variables are declared, and the formula's error stays an error at that op, saying the variable gives nothing until its formula is fixed. Rejecting it left every node that read the op's variables showing nothing (three recorded cards, reservation, checkout and itinerary by claude-sonnet-5-5, went blank once formulas were checked). -
BindValue.colorreads a theme color's name (Color.named): a fill bound to"${= selected ? 'primary' : 'primaryBackground'}"was dropped. -
A
patchop merges a node as its declarations read it (mergeNodePatch):{"height": {"fill": 400}}over{"hug": 480}gave a two-key size and the patch was rejected. -
A
setthat replaces the root canvas with another type is rejected (wrong_type, with how to set the canvas's body): a recorded retry turned its canvas into a column and the view showed nothing. -
wrong_typefor a${...}expression written as a plain value ("radius": "${theme.radii.panel}","visible": "${step > 0}") names the binding to write,"bind": {"decoration.radius": "${theme.radii.panel}"}. Five recorded base turns lost their whole card to one such rejected container. -
The design system section shows its spacing, radii and sizes as the binding to write ("bound, not written: ...") instead of the bare
${theme.radii.panel}models wrote as a value. -
New codes for what a rendered UI shows wrong, reported by the SDK's
UiSession.shownDiagnostics:empty_viewandlist_empty(errors),empty_label,expression_not_evaluated,text_no_color,component_empty(warnings). -
dead_controllint: a core button, or a component named...Buttonwith anonPressedevent, with no reaction, not disabled and not inside a tappable node (a recorded plan card was a static mock-up whose Start and Pause did nothing). -
A computed variable's
formulais checked like a node's expressions (it was not checked at all): it must parse and read only declared names, itsparametersincluded. The edit layer checks the formulas of the variables avarsop declares (EditCheckInput.variables, read bystrictEditCheck; the diagnostic's message names the variable). -
An unknown name that is a field of a list variable's records (
filter(invoices, status == 'Paid'), computed once outside the list and matching no item: a recorded data table showed "No results" over twelve defined invoices) gets a message that says so and the lambda to write (filter(invoices, r => r.status == x)), withr => r.statusas its suggestion. -
unresolvedReferences(withchangedVariables): once a stream has ended, the references accepted as warnings while it ran ("it must exist when the stream ends") that are still unresolved, as errors.streamReferenceCodesnames the codes. -
Reference: lists "Filter, sort and page a list" (search, a status filter, sortable headers and pages from chained computed variables, with a validated example; the pitfalls: a condition without its item, "All" and an empty search,
sortBy's'asc'/'desc', resetting the page), a pitfall line, a line in the base and a row in the task table.{{example-as-written:path}}puts an example in a page as its file is laid out (one node per line). -
strictEditCheckpasses its options'themeon to the validator (it dropped it): a session with a design system checks each op against the design system's tokens, so a theme color or text style name (primaryBackground,sectionTitle) is no longer rejected asunknown_theme_name. -
TrustProfile.withComponents(library): the profile with a component library's types allowed. A session given a design system checks ops with it (the SDK'sUiSession(designSystem:)):TrustProfile.agentlists the core's node types only, so every call to a design system component wascapability_not_allowed. -
A top-level
componentEvent(in a document that is not a component: a generated UI's own events to its agent) is no longerunknown_eventin document and site validation; it is an event to the document's host and needs only an"event"name. The strict edit check no longer filters the code out for this case.
No special cases left: the last 21 one-look fields are general mechanisms. Documents stay "schema": 3.
Each removed field is migrated by a one-way step at the end of migrate2to3 (steps_special.dart); in a
schema-3 document each is an unknown_prop whose message names the form to write, and a setValue path into one
is rewritten where it has a place (props.displayFormat, props.highlightStart/End) or reported. No document in
the corpus or either repository used one. Name conformance (docs/design/name-conformance.md, regenerated): 853
fields, 62% Flutter's name and meaning, 77% of those with a Flutter counterpart, none (d).
| Removed | Instead | Step |
|---|---|---|
text countUp, countUpDuration, countUpCurve, countUpOnShow |
a transition of props.text with the timing, and (with countUpOnShow, the default) an animation countUp with a track on props.text from 0 |
text.countUp |
slider rulerTicks, rulerMajorEvery, rulerTickColor, rulerMinorTickColor |
customPaint.painter ops: a baseline line and a repeat of tick lines (a ruler track's default 20 ticks too) |
slider.paint |
slider markerValue, markerColor, markerWidth, markerHeight |
a rect op at the value along slider.trackRect |
slider.paint |
slider activeTrackStartOpacity |
an rrect op over the active track: the inactive color fading out |
slider.paint |
slider thumbGripColor |
a rect op in foregroundPainter at slider.thumbCenter |
slider.paint |
slider deriveOverlayColorFromThumb |
nothing (no renderer read it) | slider.paint |
text field highlightStart, highlightEnd, highlightStyle |
runs (new on the text field: styled ranges of the typed text, as a text's; Flutter's TextEditingController.buildTextSpan) |
textField.runs |
table selectedRowEdgeColor, selectedRowEdgeWidth |
the cell template's selected state style (a left stroke), selected bound to the cell being first in the selected row |
tableView.rowEdge |
date/time input displayFormat |
format |
dateTimeInput.format |
- A number in a text counts.
AnimationTrack.lerpValue(a, b, t, text: true)(andvalueAt(..., text:),sequenceAt): a text that holds a number goes froma's number to its own, written as the end writes it (the characters around it, decimals, thousands separators; a value a clock computes a hair under a half rounds as the half).NumberInText(parse,format). A transition or track on a text prop such asprops.textcounts. - A slider's custom paint draws between its parts and reads
slider(value,min,max,trackRect,thumbCenter):SliderTrackShape.rulerdraws its strip and fill only; the ticks are ops. TextFieldProps.runs.specialCasePropsandmovedSpecialPath(legacy_paths.dart): what each removed prop is now, for validation andmovedPathHint.- Validation: a layout value written as it decodes is not an unknown key.
"widthFactor": 0(anywidthFactor/heightFactor) was reported asunknown_layout_key, with a message listingwidthFactoramong the valid keys:readsKeytook a value that encodes back unchanged for one kept verbatim in an extra map. It now probes the key with a value no reader takes. - Name conformance (
tool/name_conformance.dart): the 21 (d) verdicts go;textField.runs(b), the grid placement fields (c) anditemSnapping(b) are classified. docs/design/10-audit-verdict.md section 6 re-measured; docs/design/schema-3-migration-report.md's note after 30.1.0 regenerated over the corpus.
A site looks like itself: theme mode, declared fonts, local images. Additions only; documents stay
Design systems as data; controls that are not Material-shaped. Additions and default changes; documents stay
"schema": 3.
DesignSystem(design_system.json:DesignSystemManifest): DESIGN.md (principles), the tokens (a theme), PATTERNS.md and component definitions by reference, plusfonts,examplesandreplaces(the base controls its components stand in for).DesignSystem.load(read)reads one from a folder or a publish;fromJson/toJsonis one bundle.themeUnder(site),libraryUnder(site),catalogOver(base),list(each component's purpose and minimal call).site.json'sdesignSystemnames one (a folder relative to the manifest, or a publish id): its tokens are the site's base theme, its components callable by type.- Named theme scales:
spacing,radii,sizes,shadows(withdarkshadows),durations,curves, read as${theme.<scale>.<name>};ThemeTokens.mergedWith.validateThemechecks them; a binding naming a step the theme does not have isunknown_theme_name. - The prompt:
runtimeStarter(designSystem:)adds a section generated from it (principles and patterns in brief, tokens by name, each component with parameters, slots, events and a call) and drops the base controls it replaces;docsTopic(designSystem:)answersdesign,patterns,tokensand a component's name. A design-systems page joins the reference. - Colors that follow the theme:
tabBar(indicatorColor,labelColor,unselectedLabelColor,dividerColor),pagination(textColor,activeColor,activeTextColor,borderColor), the gauges', charts', barcode's and signature pad's palettes are now optional, unset meaning the theme's role (documented per prop): values and linesprimary, tracks and gridsoutlineVariant, ticks and axesoutline, labelsonSurfaceVariant, needles, cursors and tooltipsonSurface. dropdown.underlinenow means the field's border (the theme's outline), never Material's underline.
Earlier in this release: a site looks like itself: theme mode, declared fonts, local images. Additions only; documents stay
"schema": 3.
-
Theme mode (Flutter's
ThemeMode):ThemeTokens.mode("mode": "system" | "light" | "dark"in a theme, defaultsystem) is the mode a site starts in, and thesetThemeModeaction ({"type": "setThemeMode", "mode": "${= theme.isDark ? 'light' : 'dark'}"};modeis an expression,persistdefaults to true) changes it.ThemeMode.isDark(platformDark:)andThemeMode.tryParse. Validation reports a bad mode, or amodeinsidedarkor a media patch (invalid_theme). -
Site fonts:
SiteManifest.fonts, a list ofFontFamily(family,fonts:FontAssetwithasset,weight,style) in the shape of a pubspec'sfonts:section, the files besidesite.json.PublishFont.ofFamiliespublishes them one per file withurlthe path relative to the site (PublishFont.isSiteFile; idsFamily/weight/italic,PublishFont.idOf).validateSiteFontsreports a bad shape (invalid_fonts) and a file that is not.ttf,.otfor.woff(font_format; WOFF2 is not read). -
Site files:
isRelativeAssetPath, andPublishSource.assetPath(publish/{slug}/files/{path}), where a published site's fonts and images named by a relative path are served. -
Reference: theme mode, declared fonts and local images in the base (
STARTER.md); theme.md's dark mode and fonts sections rewritten; decoration.md's images section (local files,BoxFit/Alignment) and a new illustration section, with three validated examples (a photo card with a gradient scrim, an SVG illustration and apathmark, acustomPaintscene); render.md's--themeandfont_missing. -
Node ids are per document; only canvas ids are site-wide.
duplicate_idnow reports a canvas id two documents of a project share (navigateandopenModalname screens by it, so a link reaches one of them), and no longer every node id two pages share: a page's actions and conditions name its own nodes, a component's ids are its own. The base says so. -
Did you mean, by meaning.
nearest(thesuggestionofunknown_action_key,invalid_enumand the other name checks) falls back to the name an author usually means when none is spelled close:target→node,content/value→text,append/push→add,if/predicate→condition,screen→to. Anifwhoseconditionis a formula string is told the predicate to write ({"left": "${= ...}", "op": "isTrue"}). -
Reference: a complete multi-page site (components, "A complete multi-page site";
tool/reference/examples/site/, validated as one project by the reference test): the manifest first with every page listed, a header and a footer shared by reference, route parameters with a default, storage restored on load, a list kept per route under a key built from${route.id}, and a modal opened from a component. The base says to list every page insite.jsonbefore writing pages that link to them. -
Reference: the names authors guessed wrong, in short examples where they look:
scrollTo.node(layout),downloadFile.fileNameandtext(media),copyToClipboard.text(interaction), theifpredicate (state),setStorageops (addappends,insertat anindex) and keys per route (data). New patterns: scroll progress (layout), entrances on scroll withanimations[].visibleFractionversus therevealbehavior, which scrolls (animation), pinningnow()with the render command's--now(animation), spacing and radius scales (theme: there are no such tokens; a project variable map). The render page covers--drag,--navigatewith a query string,--now,--compare-map, what a run keeps, and full-page captures of sticky nodes, modals and navigation. -
A stroke path's draw-on animation migrates to the general pieces.
strokePath.drawMs(withdrawDelayMs,drawCurve) was kept aslegacy.strokePath.drawand no longer drawn;paint.strokePathnow writes an animationstrokePathDrawwhose track draws the line op'strimEndfrom 0 to its own value (the fill's paint from transparent), played when the node appears, and a transition of thattrimEndwith the same timing; a bound progress becomes a binding ofcustomPaint.<painter>.strokePath.trimEnd. Frame for frame the old painter's drawing (codelessly_sdk'sstroke_draw_on_test.dart), except a progress that changes while the line is still drawing on. A literaldrawKeyis dropped (it never changed).legacy.strokePath.drawis no longer written. -
BindPaths.declaredDefault(node, path): the declared default at a binding path (opacity,props.*,layout.*,decoration.*, a custom paint op's field), the node's value there when its JSON omits the field. An animation track with nofromortouses it (codelessly_sdk), so a track can end at an op's defaulttrimEnd1. -
Name conformance, re-measured (
tool/name_conformance.dart; docs/design/10-audit-verdict.md, section 6, and docs/design/name-conformance.md): 61% of the 863 declared fields of the Flutter-mirroring node types and shared groups are Flutter's name and meaning, 78% of those with a Flutter counterpart; 21 special-case fields are listed with a recommendation. -
A time picker's
use24hisalwaysUse24HourFormat(Flutter'sMediaQueryData.alwaysUse24HourFormat, which the picker reads). Stepprops.renamed(inmigrate2to3's one-way steps) renames the prop, its binding, state and media patches andsetValue/condition paths in a schema-2 document; in a schema-3 documentuse24his refused (unknown_prop) naming the new spelling, andmovedPathHint('props.use24h')gives it. No document in the corpus or either repository used it. -
State patches that targeted
selfor@<key>now run. A state patch names the node it patches by id; generated schema-2 documents also wroteselfand@<key>(the node's key), which matched no node, so those hover, press and selection styles never applied (1131 patches in 9 corpus documents, all naming the node their states are on).migrate2to3's first step,states.target, rewrites them to the id they mean and reports a behavior change. In a schema-3 document validation refuses them (unknown_target_node) with the id to write as the suggestion.
Forms, grid placement and scroll control, in Flutter's shape (and CSS's where the responsive model follows the web); documents written for 30.1.0 load unchanged.
- Forms.
textField.validatoris Flutter'sTextFormField.validator: an expression that reads the typed text asvalueand gives the error to show (""when valid), checked by validation withvalueas a name. The object form older documents saved ({"type": "required"},{"type": "email"}, never applied) reads as the expression it named.AutovalidateModegains Flutter'sonUserInteractionIfError. formbehavior (Flutter'sForm, withautovalidateMode): the fields inside validate together; its nodes read${form.valid}and${form.errors}({field, label, message}, top to bottom).formis a runtime scope.validateaction (FormState.validate()): every field of the form (node, else the form around the reaction's node) shows its error, the first invalid one takes the focus (focusFirstError),${result}is whether all are valid.radioGroupbehavior (Flutter'sRadioGroup): radios inside take its bindablegroupValue; choosing one runs the group'schangedreactions.- Grid placement.
layout.columnSpan,rowSpan(CSSgrid-column: span n) andcolumnStart,rowStart(grid-column-start, 1 the first) are child fields agridViewreads; elsewherelayout_field_ignored. - Scroll control.
itemSnappingon scrolling rows, columns, lists and grids (PageView.pageSnappingfor items; CSSscroll-snap-align: start); thescrollandscrollEndtriggers document${result.index}(the item at the start of the view) and${result.count}. - Validation.
state_no_effect: a boundselectedwith nostates.selectedpatch changes nothing (a chip's selection isprops.selected). - Reference. Worked, validated examples: a complete contact form (per-field errors on blur and send, a summary,
a radio group, a success state), an editorial page at 390/834/1440 (one column, a split with a sticky rail, a
three-column river with a spanning lead), a timetable that is a list on a phone, and a carousel with arrows, dots,
progress and snapping. The base says to use the width at tablet and desktop. Where node-given names are read
(
pageOffsetis a page view's, not a page's scroll), and how runs that cut an expression count, are stated.
One spelling for each concept; the schema stays 3. Documents are still "schema": 3 (kSchemaVersion), and
schema-2 documents still load, migrated in memory by migrate2to3, whose last steps now give each concept that
30.0.0 could say two ways one spelling, under Flutter's name. 30.0.0's schema-3 documents keep loading as
schema 3; but a schema-3 document is read as it is, not upgraded, so one written with the earlier spellings below
must be updated once (the migration does it to schema-2 documents; validation reports each earlier spelling in a
schema-3 document as an error naming the one to write). docs/guide/12-migrating-to-schema-3.md ("30.1.0") is the
authors' guide; docs/design/schema-3-migration-report.md the migration over the corpus (106 documents, 0 failures,
3502 rewrites of which 1020 by the new steps; 5 behavior changes by the new steps, all a box path's, in two m05
experiments).
| 30.0.0 (schema 3) | 30.1.0 (schema 3) |
|---|---|
a node's "scale": s |
"motion": {"scale": s × the motion's own} |
"layout": {"rotation": r} |
"motion": {"rotate": r + the motion's own} (an uneven margin's pivot offset as motion.translateX/Y) |
flightKey, flight |
"hero": {"tag": ..., "flies": "inPlace", "flight": {...}} |
"hero": {"flight": "<look>"} |
"hero": {"flightShuttle": "<look>"} |
"strokePath": {...} |
a customPaint path op (points or commands, trimEnd for the progress) |
a box with props.path, strokeJoin, strokeMiterLimit |
a path node, the path as props.data |
a path's subpathColors |
one customPaint path op per color |
a paint's gradientPerSubpath |
one customPaint path op per shape, the gradient as its paint's shader |
binding, transition, track, setValue and condition paths scale, layout.rotation, flightKey, flight.*, hero.flight (a look), strokePath.*, props.path, props.subpathColors |
motion.scale, motion.rotate, hero.tag, hero.flight.*, hero.flightShuttle, the custom paint op's fields, props.data |
- Docs: controls take the theme, never Material's defaults. The reference's base and its theme page say what
controls take from the theme's roles (
primaryfills filled buttons and draws checks, thumbs and text-button labels where it reads onsurface;fontFamilyevery control label;buttonRadiusevery button and chip), that without a theme they are neutral (ink on paper and the greys between), and that nothing comes from Material's defaults or from the host app's theme. No API change: the roles already cover it (outlines and tints are derived fromonSurfaceoversurface, so nooutlinerole is added). - Breaking, Dart: fields removed.
Behaviors.scale,Layout.rotation,BehaviorFields.scale,LayoutFields.rotation,BindPaths.scale,BindPaths.rotation;Behaviors.flightKey,Behaviors.flight,BehaviorFields.flightKey,BehaviorFields.flight(HeroTaggainsflies,HeroFliesandflight; its look isflightShuttle);StrokePath,PathUnit,PathCurve,StrokePathFields,strokePathType,BehaviorFields.strokePath,Behaviors.strokePath;BoxProps.path,BoxProps.strokeJoin,BoxProps.strokeMiterLimit;PathProps.subpathColors;Paint.gradientPerSubpath,PaintFields.gradientPerSubpath; thedeprecated_keydiagnostic. The catalog's declared fields go from 2121 to 2099 for the paint fields alone. - Added: a
customPaintpath op'scommands(Flutter'sPathcallsmoveTo,lineTo,quadraticBezierTo,cubicTo,close, each number a literal or a formula, each call with an optionalwhen;PathCommand,PathOpFields.commands);PathProps.strokeMiterLimit;migrateDocument,migrateNode(any schema to 3) andmigrateJson;MigrationScope.document(a node step reads the document it is in);movedPathHintandolderSchemaPathHint(what to write for a moved path set at run time). - The migration's new steps (
steps_spellings.dart,steps_transform.dart,steps_hero.dart,steps_paint.dart), after schema 2's:transform.fold(scale multiplied intomotion.scale, rotation added tomotion.rotate, the pivot kept, bindings, transitions, tracks and keyframes moved),hero.flight,paths.moved(setValueand condition paths), the paint steps (paint.patches,paint.strokePath,paint.boxPath,paint.perShape; what has no exact form is kept aslegacy.<name>and reported, e.g. the draw-on animation aslegacy.strokePath.draw), thenpatches.moved(state and media patches). Rendered before and after, every affected corpus node draws the same pixels except a box path's filled edge (at most 4/255) and a box path reaching outside its box, now filled there too (reported). - Validation: an earlier spelling in a schema-3 document is an error naming the one spelling
(
unknown_node_key,unknown_layout_key,unknown_prop,unknown_field,unknown_bind_pathfor a binding, transition, track,setValueor condition path,wrong_typefor a look written ashero.flight). A custom paint's ops may readsize, and itsviewBoxmay be[width, height](as the decoder reads and writes it). Alegacy.<name>islegacy_value(a warning), held inNode.extra, never drawn. - The plot chart's Cartesian props stay: they are the chart's general features (docs/design/01-paint-node.md, "30.1.0").
- Reference: regenerated; one spelling for each concept throughout.
The reference for authors is one base plus links. docs/reference/STARTER.md is the base an agent reads in
full (the document and the flat node map; layout, decoration, text with a theme; the base node types and which
types take children or slots; variables, bindings, reactions; media rules; the rules that are easy to get wrong;
an index); every other feature area is a page with the same six sections (When to use, Minimal example,
Reference, Patterns, Pitfalls, See also); index.md maps needs and every declared name to their section. Each
node type, behavior, trigger, action, model, enum, value type and formula function is on exactly one page
(tool/reference/src/areas.dart; a test checks it, and that every link and anchor resolves).
- One base, two forms.
baseDocument({form, catalog, profile, kind, docsTool})assembles the base from the generated segments oftool/reference/templates/base.md:BaseForm.filesisSTARTER.md(with checking your work and sites as files),BaseForm.runtimeisruntimeStarter()andRUNTIME_STARTER.md(with the answering rules, the ops and two examples). The runtime base is about three times the earlier one (≈ 43k characters against 15k): it now carries the theme, layout patterns, the children table and the index. ui_docsserves the pages.docsTopicanswers a page (When to use, minimal example, pitfalls, its sections), any section by its anchor, or any node type, action, trigger or behavior by name;docsIndexis the index the base ends with;docPages,docTasksare the generated data;toRuntimeLinksturns the files' links intoui_docstopics. Earlier topic names (responsive,reactions,gestures,scripts...) still answer.starterProps,behaviorAreasandguideTopicsare gone (baseProps,docPages).- Machine forms.
catalog.jsonnames each node type's, action's, behavior's and trigger's page and anchor (docs);index.jsonlists every topic with its file, anchor, summary and size. - Retired.
nodes.md,behaviors.md,triggers.md,actions.md,bindings.md,formulas.mdandvariables-conditions-scripts.mdare stubs that keep their anchors and say where each item went; the old guide'sindex.md#guide-...anchors land on a table of where each section went;API_REFERENCE.compact.mdis gone (the base's runtime form replaces it);API_REFERENCE.mdis the base, the index and the pages in order. - Docs at the declarations for the props and fields the base shows.
Schema 3: the one planned format break. Documents are "schema": 3. Schema 2 documents load and are
migrated in memory; write schema 3. LayoutDocument.fromJson (and PublishModel, PublishBundle,
PublishLayout, PublishComponent, ComponentDefinition, the site manifest and plugin packages, through
the documents they hold) migrates a schema-2 document (or one with no schema) before decoding it; encoders
write "schema": 3. The guide's new chapter, docs/guide/12-migrating-to-schema-3.md, is the authors' migration
guide; docs/design/schema-3-migration-report.md is the migration over the reference apps and experiments.
- The migration:
migrate2to3(Json document, {MigrationReport? report})(pure, total, idempotent),migrateNode2to3,migratePublish2to3,migrateJson2to3(any file that carries documents; a stored payload or a stored published component, whose digest covers what was stored, is migrated when read),schemaOf,kSchemaVersion= 3,kPublishSchemaVersion= 3,schema3Steps(namedMigrationSteps).MigrationReportlists every rewrite, every value with no schema-3 form (kept on the node aslegacy.<name>, unread, with what to write instead) and every behavior change;migrationReportMarkdown. Commands:dart run tool/migrate.dart <file|dir> [--write] [--report out.json],dart run tool/migration_corpus.dart(corpus checks and the aggregated report). - Validation:
validateDocumentreads 2 and 3: a schema-2 document gets theschema_outdatednote (Severity.info) and is validated as migrated;legacy_value(warning) flags a kept value; an expression is accepted where a field takes one inline (ExprCodec: a timer'sintervalMs). - Breaking (Dart): the legacy readers are gone from the model; the migration has them.
Behaviors.migrateBind,Behaviors.legacyKeys,Behaviors.effectiveTransformGesture(usetransformGesture),TransformGesture.zoomable,DragRelease,Spring.legacy,PathFollow.fromLegacy,Track.fromLegacyDrag,Track.readsOnly,DismissibleBehavior.fromLegacyDrag,Pan.fromLegacyDrag,AnimationPresets.fromLoop,fromEffect,fromMotion,fromPulseKey,legacyLoopMode,loopTypes,effectTypes,legacyMotionSpring;SetVariableAction.animateMsandcurve(SetVariableFields.animateMs,curve). Decoders no longer readloops,effectAnimations, motion's temporal keys,opacity,blur,originX/Yand flat path keys,drag,zoomable, a track'sendAngle/endless/jumpOnTap/wheel/keyboard/momentum/friction/write/settleStiffness/path string, a draggable'swhileDragging/feedbackNodeId/feedbackAnchor/dragAnchorStrategy/spring*/physics, flat physics springs, thetransitionsobject and map,gradientUnits,playAnimation,animateVariable,setVariable.animateMs,controlDrag, theclocktrigger: in a schema-3 document they are unknown keys (kept, unread). - Breaking (Dart and JSON): the deprecated one-app fields are removed (the migration keeps a value that
did something as
legacy.<behavior>.<field>and reports what to write instead):Track.defaultValue,doubleTapValues,parkedProgress,fineStep,finePixelsPerRange,fineHold,fineVariable,smooth,gain(andhasFine,isParked,doubleTapTarget,effectiveFinePixelsPerRange,${track.fine});DismissibleBehavior.restX,restY,xVariable,yVariable,flyOutRotate; onDismissibleBehaviorandPan:rotateFactor,originX,originY,shakeWhenDisabled,disabledFollow,shareAs,follow;PathFollow.pacing,focus,pacedByArea,headsLeft,PathPacing,PathOrient.uprightFlip(nowupright);Transition.arc;DropTarget.fullIf,slotWhenRefused(the slot opens for accepted drags only),hoverDelay, and thedropFullanddragHovertriggers;GestureSnap.projectVelocity(a snap always projects the fling);TransformGesture.rotationSnap;OpenModalAction.showCloseButton,fullHeight(never read). Their*Fieldsdeclarations go with them. - Flutter's reading where schema 2 had its own (the migration writes out what schema 2 did, so migrated
documents render the same): a text's
layout.paddingis applied (Padding(child: Text), counted in a hugging size); schema 2 ignored it and the migration drops it from schema-2 texts (steptext.padding, with the bindings and state and media patches that set it). Thelayout_field_ignoredwarning for a text's padding is gone. A text style without aheighttakes the inheriteddefaultTextStyle(new behavior on any node, Flutter'sDefaultTextStyle: the nearest one wins,{}gives Flutter's defaults back), else the font's own line height (Flutter'sheight: null), not 1.33; the migration keeps 1.33 for schema-2 documents with one"defaultTextStyle": {"height": 1.33}per top-level node (steptext.lineHeight; +0.08% bytes over the corpus). Breaking (Dart and JSON):TextStyle.naturalHeight(TextStyleFields.naturalHeight),ThemeTokens.naturalLineHeightandStyleSheet.naturalLineHeightare removed; the migration turns a natural style into its node's"defaultTextStyle": {}, and drops (reporting) a theme's flags, which a document migrated on its own cannot see.migrateJson2to3andmigratePublish2to3drop them from carriers;dropNaturalLineHeightFlags.tool/migration_corpus.dartreports the encoded size before and after. - Paths an action names (
setValue'svalues[].path) are not migrated:schema2PathHint(path)gives the schema-3 path for a schema-2 one, andunknown_bind_pathsays it (motion.originX→motion.alignment,loops[i].<key>→animations.loop<i>.<key>,drag.track.<key>→track.<key>...). - Behavior changes (all reported by the migration, per document): a track with no value is drawn at
its minimum, not at
defaultValue, and a double tap resets nothing; the fine mode,smooth, a dismissible's tilt and fly-off spin, disabled follow and shake,shareAs, area pacing, the upright flip, a transition's arc,fullIf/dropFulland a hover delay no longer act; a refused drag opens no list slot; asetVariableglide that is not a set, add or subtract by one formula sets at once. Over the corpus: cutroom's fine step and safecracker'ssmooth(docs/design/schema-3-migration-report.md).
Streaming generative UI, hardened against real model output
OpStreamDecoderrecovers every well-formed op from tool input that is not valid JSON (eager tool input streaming does not promise it; a recorded live generation closed one brace too many three times): a repaired copy of the text (stray closers dropped, missing ones inferred, trailing commas removed, missing commas inserted), op objects read at any depth outside another op, re-synchronisation when an op begins before the previous one closed. Each repair is onemalformed_inputwarning with the character offset;OpStreamEnd.repairsand.recovered;StreamedOp.recovered. A set op's node fields written beside"node"move into it (misplaced_field). Property tests: any chunking yields the same ops; 2,000 single brace, bracket or comma edits lose no op but the one they land in; the three recorded live generations decode whole (24, 50, 34 ops).- The retry protocol:
EditResult.toModelJson()says what the document holds (ids set, patched, moved, removed; roots, node count, pending) and, when anything is rejected or pending,next(fix by patching, same ids, never start over);fixInstruction;EditResult.withDiagnostics.applyOps(protectRoots: true)answers a batch that would replace the roots or add a canvas withstart_over.explainDiagnosticspells out the fix for the codes models hit (unknown_layout_key hug,children_not_allowedandinvalid_parentwith the types that take children, a button'stext,would_orphan,canvas_as_child);atOpmoves the op path with the index. uiLints:empty_button,low_contrastand, with aGlyphCoverage,missing_glyph(with the icon to use); codesno_sizefor renderers;fontCodepointsreads a font's cmap.- The runtime docs:
runtimeStarteris the base set a chat card or small screen needs (layout, decoration and text essentials; one table of the base node types with what takes children and their key props, the button family and the inputs and lists included; state, bindings, reactions; two examples that apply cleanly), generated from the declarations;docsTopicanswers theui_docstool for any node type, action type, trigger, behavior or feature area (the guide's sections,guide_topics.g.dartwritten by the reference generator);docsIndexis the base's index.uiTools(catalog, compact: true, docs: true): the op envelope strictly plusui_docs;ui_readtakestypes(describeTypes). Generated:docs/reference/RUNTIME_STARTER.md,ui_tools.compact.json. TrustProfile.agentApps:agentplus the document's sandboxed scripts (capabilitiesvariables.read,variables.write,clock;TrustProfile.scriptCapabilities). Thescriptsop sets and removes them by name (ScriptsOp,invalid_script), with an inverse for undo.
Components in published apps, hosted plugins as components (sections and components, phase 2)
PublishModel.components({type: {version, digest, lastUpdated, fonts}},PublishComponentInfo),PublishLayoutInfo.components(the closure a layout calls),PublishComponent(stored atPublishSource.componentPath:publish/{p}/components/{type},{"schema": 2, "id", "version", "digest", "document"}; a document decoded from a store is written back as stored),PublishBundle.componentsandPublishBundle.extra.PublishModel.fontsOfadds the fonts of the components a layout calls.canonicalJson: what a component's digest (sha256, computed by the publisher) is over.- Hosted plugins on the components' path:
PluginWidget.definitionJsonandPluginPackage.definitionsturn a plugin node type into a component definition (its catalog declaration aswidget, its slots asslotnodes, its events declared, its formula functions as the root's variables).PublishBundlePlugins(pluginVersions,withPluginVersions): plugin payloads embedded in a bundle. - Validation:
repeated_subtree, a newSeverity.info: a subtree of three or more nodes written several times over, node for node (ids and names aside), with the copies' ids: "consider a component or a list template". Only exact repeats; a repeat inside a reported one is not reported again. - Docs: DESIGN.md §2.1, §4.2, §4.3, §5.4; docs/design/06 and 05 "Done" / "Not done"; the guide's components
section (published sites, per-instance rules, slots inside lists, plugins as hosted components,
--components-all,repeated_subtree).
Authoring fixes from the third direct-authoring experiment (cycle 3)
- Named colors and text styles. The site manifest declares the project's theme (
SiteManifest.theme: colors, text styles, roles,dark, andThemeTokens.media, rules that patch the theme by screen size); a color field may name one of its colors ("color": "ember", kept through decode and encode asColor.named) and a text style may start from a named one ("style": "title", or{"from": "title", ...}:TextStyle.from, merged asTextStyle.merge).ThemeTokens.color,textStyle(resolved:fromchains, colors by name, aliases),atScreen;ThemeRefs/resolveThemeRefsresolve a node or a document by its declarations (props, decoration, behaviors, media and state patches), leaving the nodes that name nothing the same objects.Color.fromHexreads values only (the oldfromJson). A media or state patch that names another style replaces the style; one that changes fields merges over the named style. New diagnosticsunknown_theme_name(with the nearest name) andinvalid_theme;validateTheme;ValidateOptions.theme(the manifest's by default). Behavior change (documents that validated stay the same): a color string that is neither a hex color nor anything else ("blue") decoded to null and now decodes as an unresolved theme name (transparent); validation reported it before and reports it now. IconProps.size(Flutter'sIcon.size).- A media rule's patch may set
bind(bindings at its sizes only;nulldrops one of the node's) andmotion(a paint-only transform).media_overriddensays how to combine a rule and a binding. layout_clampedpoints to the overlap patterns (motion translate, a stack).- Docs: the guide and the starter lead with the theme; overlapping a neighbor, bleeding past the gutter, a
verified full-width band with capped content and a table from one cell template, form control styling,
foregroundFillsover children, a literal$before an expression, superscripts, arrow keys throughkeyDown, component parameter kinds; the allowed-modes table marks fill withbasisin a wrapping row;bindings.mdlists what each path expects.
Authoring fixes from the second direct-authoring experiment (cycle 2)